This is the presentation I did with my colleague Nuno Baptista for NextStep 2012

1. How to Design a Good API?
2012-05-11
www.outsystems.com Page 1 © 2012 OutSystems – all rights reserved

2. What is a Good API?
Hard to Leads to
misuse readable code
Stable
Easy to learn
Complete
and memorize
www.outsystems.com Page 2 © 2012 OutSystems – all rights reserved

3. What to consider?
User Stories Logging
Naming Versioning
Granularity Scalablility
Error Handling Security
www.outsystems.com Page 3 © 2012 OutSystems – all rights reserved

4. User Stories
• Who will use the API?
• How will they use it?
• Where will they use it?
• Put yourself in the developer’s shoes!
Naming & Type
• Meaningful & Readable
• Consistent
• Strongly typed
www.outsystems.com Page 4 © 2012 OutSystems – all rights reserved

5. Granularity
GetOrderDetail()
CalculateTotalAmount()
GetEmployeeName()
3 x GetOrderLine()
www.outsystems.com Page 5 © 2012 OutSystems – all rights reserved

6. Error Handling
www.outsystems.com Page 6 © 2012 OutSystems – all rights reserved

7. Logging
• Measure Usage
• Performance Monitoring
• Troubleshoot
• Service Center helps you out!
Versioning
• Go public means you have to version
• No usage = deprecate old version
• It’s costly so avoid it!
www.outsystems.com Page 7 © 2012 OutSystems – all rights reserved

8. Scalability
• Use Partial Response
– Pagination
– Filtering
• agileplatform™ already scales!
Security
• Control access to API for internal
• HTTPS/SSL for Public APIs
• Token-based Authentication
www.outsystems.com Page 8 © 2012 OutSystems – all rights reserved

9. API is a Product!
www.outsystems.com Page 9 © 2012 OutSystems – all rights reserved

10. Scenarios
www.outsystems.com Page 10 © 2012 OutSystems – all rights reserved

11. Master data
Most companies want to centralize their master
data.
- Nouns and Verbs Naming
Applications
Composite
Directory Performance - Read-only Entities Security
Management
-Throw Exception Error handling
Core Business
Components
- TrueChange™ Versioning
Employees
www.outsystems.com Page 11 © 2012 OutSystems – all rights reserved

12. Information Provider
Airport management company provides real time flights’
information to their clients
3rd Parties
- Lifetime Token Security
- Custom Audit Logging
agileplatform™
Flight - Partial Response Scalablility
Services
- API Document Documentation
Airports Flights - New WebService Versioning
www.outsystems.com Page 12 © 2012 OutSystems – all rights reserved

13. 3-Tier Layer
Bank company wants a CRM application with a
SOA approach. Security is critical.
- Int. Auth, Int. Net. Security
UI Layer
1
CRM HomeBank
- Resource based User Stories
Business Layer
Account Customer - Cache Scalablility
Services Services
2
- OutDoc Documentation
Accounts Customers
www.outsystems.com Page 13 © 2012 OutSystems – all rights reserved

14. Extranet
Insurance company wants to scale out claim management
through partners.
Small Large
Partners
- Use reUse Granularity
Partners
- Return error Error Handling
WebPortal
- Application Log Logging
agileplatform™
Claim
Services
- HTTPS + S.Token Security
Claim Management
www.outsystems.com Page 14 © 2012 OutSystems – all rights reserved

15. What is a Good API?
Hard to Leads to
misuse readable code
Stable
Easy to learn
Complete
and memorize
www.outsystems.com Page 15 © 2012 OutSystems – all rights reserved

16. Steve Jobs

17. www.outsystems.com Page 17 © 2012 OutSystems – all rights reserved

18. andre.vieira@outsystems.com nuno.baptista@outsystems.com
www.outsystems.com Page 18 © 2012 OutSystems – all rights reserved