Post on 12-Aug-2015
API Craft - Meetup
• API Design
• Various API Platform Analysis – Use Cases
• Building API Server as a tier
• API Server -- Mobile App
• Usergrid
• API Studio
• Apigee 127
API Craft - Meetup• Why APIs ?
• API Design Best Practices
• Importance of API Server
• Usergrid – Removing a server side layer
• Introduction to Apigee 127, Hands On
• Introduction to Usergrid, Hands On
• App Contest - Hackathon
• Code Sprints – Open Source Contribution
9
APIs
Web
Point of Sale
Partner
App, API, Analytics Infrastructure
Mobile
ESB, SOA,App Servers,Databases
Backend Services
12
Digital requires the right foundation
API and data
Reporting andmonitoring Monetization
Globaldeployment
Security
OnboardingAPIdocumentation
Developerauthentication
Mobileoptimization
Trafficmanagement Partner
customization
Transformation
Versioning
Predictive
analytics
Data
REST APIs
• Architecture Style – Not a Standard
• Performance, Scalability, Simplicity
• Typically, Communicate over HTTP
• Using HTTP Verbs– GET– POST– DELETE– PUT
Singular Nouns or Plural Nouns ?
• Avoid Mixed Model
• Consistent
• Prefer plural names– Reads more Easily– Intuitive
Concrete Names are better than abstract…
• Abstractions is Not Always Meaningful
• Depends on your scenario
• Keep Number of Resources between 12 - 24
Complexity – Put it behind the ?
• States that can be updated, changed, queried
• Attributes associated with resource
Handling Errors – Best Practices
• Granular Error Messages
• Link to Documentation
• Aligning Errors with Status Codes
• Verbose as Possible
Handling Errors – Status Codes
• Start With 3 Codes– 200 – OK – Everything is Fine– 400 – BAD REQUEST – Something wrong with App– 500 – INTERNAL SERVER APP – Something wrong
with Server
• Not more than 8 Codes– 201 , 304, 404, 401, 403
Handling Errors – Status Codes
• Start With 3 Codes– 200 – OK – Everything is Fine– 400 – BAD REQUEST – Something wrong with App– 500 – INTERNAL SERVER APP – Something wrong
with Server
• Not more than 8 Codes– 201 , 304, 404, 401, 403
Versioning
• Never Release without Version– /v1/dogs
• Simple Ordinal Number
• Atleast one version back
• How long to maintain version ?– One Developer Cycle
Pagination & Partial Response
• Pagination– Offset– Limit
• Include Meta Data
• Set Defaults
• Partial Response– As optional Parameter– /dogs?fields=name,color,location
Support Multiple Formats
• Support Multiple Formats of Data– JSON– XML
• Default format ?
• Syntax– Google : ?alt=json– FourSquare : /venue.json– Digg : Accept : application/json
Secure Your APIs
• Many Schools of Thought– OAuth 1.0 a : Twitter– Permissions Service API : Paypal– OAuth 2.0 : Facebook
• What should you do ?– OAuth 2.0
Other API Tips…
• Attribute Names – Camel Case
• Search– /dog?q=red– /owners/5678/dogs?q=fluffy+fur– /search.xml?q=fluffy+fur
• Consolidate API Requests in one domain– Developers.example.com
• Complement with SDKs
Access Tokens
Identification info from the requesting application (client ID and secret)
+Resource owner credentials (if needed)
+Optional information about what the application wants to do with the resource (scope)
=Access Token and (optional) refresh token
Access Tokens are credentials that allow access to a protected resource for a specific application to perform only certain actions for a limited period of time.
Refresh Tokens
Identification info from the requesting application (client ID and secret)
+Refresh token
+Optional information about what the application wants to do with the resource (scope)
=Access Token
Refresh Tokens, if provided, represent a limited right to reauthorize the granted access by obtaining new access tokens.
© 2013 Apigee Confidential – All Rights Reserved
Common API Provider Concerns
ProtocolTransformation
Mobile Optimization
Versioning & Enrichment
Security Mediation
Traffic Management
© 2013 Apigee Confidential – All Rights Reserved
Common API Provider Concerns
ProtocolTransformation
Translate between REST to SOAP
Translate between XML & JSON
Mix HTTP and HTTPS Targets
2 Way SSL Target Security
Manage External Data Sources
© 2013 Apigee Confidential – All Rights Reserved
Common API Provider Concerns
Mobile Optimization
Compression & Decompression (gzip)
Manage Pagination
Streaming Payload Options
© 2013 Apigee Confidential – All Rights Reserved
Common API Provider Concerns
Versioning & Enrichment
Emulate Prior Release
Mock New, Unavailable Services
Mashup Data from Different Sources
Mashup Functionality from Different Sources
© 2013 Apigee Confidential – All Rights Reserved
Common API Provider Concerns
Security Mediation
App Level Authentication
User Level Authentication
Custom Attributes/Key Translation
Granular Analytics
© 2013 Apigee Confidential – All Rights Reserved
Common API Provider Concerns
Rate Limit / Quota Management
Spike Arrest
Code Injection Blocking
DoS Protection
Bogus Traffic/Probing Block
Custom Rule Enforcement
Traffic Management