How to design a good OutSystems API
18
How to Design a Good API? 2012-05-11
Transcript of How to design a good OutSystems API
How to Design a Good API? 2012-05-11
What is a Good API?
Easy to learn and memorize
Leads to readable code
Hard to misuse
Stable
Complete
Logging
Versioning
Scalablility
Security
Naming
Error Handling
User Stories
Granularity
What to consider?
• 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
GetOrderDetail()
GetEmployeeName()
CalculateTotalAmount()
3 x GetOrderLine()
Granularity
Error Handling
• 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!
• Control access to API for internal
• HTTPS/SSL for Public APIs
• Token-based Authentication
Scalability
Security
• Use Partial Response
– Pagination
– Filtering
already scales!
API is a Product!
Scenarios
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
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
Flight
Services
Flights Airports
3rd Parties
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
Extranet
Insurance company wants to scale out claim management through partners.
Security
Large
Partners
Claim Management
Claim
Services
WebPortal
- HTTPS + S.Token
Granularity
Error Handling
- Use reUse
- Return error
Logging - Application Log
Small
Partners
What is a Good API?
Easy to learn and memorize
Leads to readable code
Hard to misuse
Stable
Complete
Steve Jobs
