Languages
Pages
Legal
www.outsystems.com
Page 1 © 2012 OutSystems – all rights reserved
How to Design a Good API? 2012-05-11
www.outsystems.com
Page 2 © 2012 OutSystems – all rights reserved
What is a Good API?
Easy to learn and memorize
Leads to readable code
Hard to misuse
Stable
Complete
www.outsystems.com
Page 3 © 2012 OutSystems – all rights reserved
Logging
Versioning
Scalablility
Security
Naming
Error Handling
User Stories
Granularity
What to consider?
www.outsystems.com
Page 4 © 2012 OutSystems – all rights reserved
• Who will use the API?
• How will they use it?
• Where will they use it?
• Put yourself in the developer’s shoes!
User Stories
Naming & Type
• Meaningful & Readable
• Consistent
• Strongly typed
www.outsystems.com
Page 5 © 2012 OutSystems – all rights reserved
GetOrderDetail()
GetEmployeeName()
CalculateTotalAmount()
3 x GetOrderLine()
Granularity
www.outsystems.com
Page 6 © 2012 OutSystems – all rights reserved
Error Handling
www.outsystems.com
Page 7 © 2012 OutSystems – all rights reserved
• Go public means you have to version
• No usage = deprecate old version
• It’s costly so avoid it!
Logging
Versioning
• Measure Usage
• Performance Monitoring
• Troubleshoot
• Service Center helps you out!
www.outsystems.com
Page 8 © 2012 OutSystems – all rights reserved
• Control access to API for internal
• HTTPS/SSL for Public APIs
• Token-based Authentication
Scalability
Security
• Use Partial Response
– Pagination
– Filtering
• agileplatform™ already scales!
www.outsystems.com
Page 9 © 2012 OutSystems – all rights reserved
API is a Product!
www.outsystems.com
Page 10 © 2012 OutSystems – all rights reserved
Scenarios
www.outsystems.com
Page 11 © 2012 OutSystems – all rights reserved
Master data
Most companies want to centralize their master data.
Error handling
Naming
Co
mp
osite
Ap
plic
atio
ns
Directory Performance
Management
- Nouns and Verbs
Versioning - TrueChange™
-Throw Exception
Security - Read-only Entities
Co
re B
usin
ess
Co
mp
on
en
ts
Employees
www.outsystems.com
Page 12 © 2012 OutSystems – all rights reserved
Information Provider
Airport management company provides real time flights’ information to their clients
Logging
Versioning
Scalablility
Security
Documentation
- Custom Audit
- New WebService
- Partial Response
- Lifetime Token
- API Document
ag
ilepla
tform
™
Flight
Services
Flights Airports
3rd Parties
www.outsystems.com
Page 13 © 2012 OutSystems – all rights reserved
3-Tier Layer
Bank company wants a CRM application with a SOA approach. Security is critical.
User Stories
Security
Scalablility
- Int. Auth, Int. Net.
- Cache
- Resource based UI Layer
HomeBank CRM 1
Documentation - OutDoc
Busin
ess L
ayer
Account
Services
Accounts Customers
Customer
Services
2
www.outsystems.com
Page 14 © 2012 OutSystems – all rights reserved
Extranet
Insurance company wants to scale out claim management through partners.
Security
Large
Partners
Claim Management
ag
ilepla
tform
™
Claim
Services
WebPortal
- HTTPS + S.Token
Granularity
Error Handling
- Use reUse
- Return error
Logging - Application Log
Small
Partners
www.outsystems.com
Page 15 © 2012 OutSystems – all rights reserved
What is a Good API?
Easy to learn and memorize
Leads to readable code
Hard to misuse
Stable
Complete
Steve Jobs
www.outsystems.com
Page 17 © 2012 OutSystems – all rights reserved
www.outsystems.com
Page 18 © 2012 OutSystems – all rights reserved
Top Related