The document discusses key considerations for designing a good API. A good API should be easy to learn and memorize, hard to misuse, lead to readable code, and be stable and complete. The document outlines factors like user stories, naming, granularity, error handling, logging, versioning, scalability, and security that API designers should consider. It provides examples of APIs for scenarios like managing master data, providing flight information, implementing a three-tier architecture, and enabling an extranet for insurance claims.

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