www.outsystems.com Page 1 © 2012 OutSystems – all rights reserved How to Design a Good API? 2012-05-11
OutSystems - How to Design a Good OutSystems API - NextStep 2012
May 12, 2015
A well-written API can be a great asset to the organization that wrote it and to all that use it. This session will present simple examples to highlight the the top rules for writing good and bad APIs using the Agile Platform.
Welcome message from author
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
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
Related Documents
