API Design Best Practices & Tech Talk : API Craft Meetup @ Apigee
•Descargar como PPTX, PDF•
4 recomendaciones•755 vistas
Recomendados
Recomendados
Más contenido relacionado
La actualidad más candente
La actualidad más candente (20)
Destacado
Destacado (20)
Similar a API Design Best Practices & Tech Talk : API Craft Meetup @ Apigee
Similar a API Design Best Practices & Tech Talk : API Craft Meetup @ Apigee (20)
Último
Último (20)
API Design Best Practices & Tech Talk : API Craft Meetup @ Apigee
- 1. APIs Tech Talk API Craft Meetup – 20 June 2015
- 3. 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
- 4. 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
- 5. • Why (REST) APIs ? • API Eco System • Web API Design • Q & A Today’s Overview
- 6. Why ( REST ) APIs ?
- 8. 8 APIs
- 9. 9 APIs Web Point of Sale Partner App, API, Analytics Infrastructure Mobile ESB, SOA, App Servers, Databases Backend Services
- 10. API Eco System
- 12. 12 Digital requires the right foundation API and data Reporting and monitoring Monetization Global deployment Security Onboarding API documentation Developer authentication Mobile optimization Traffic management Partner customization Transformation Versioning Predictive analytics Data
- 13. API Tools & Softwares
- 14. 14 APIs…
- 15. Web API Design
- 16. REST APIs • Architecture Style – Not a Standard • Performance, Scalability, Simplicity • Typically, Communicate over HTTP • Using HTTP Verbs – GET – POST – DELETE – PUT
- 17. Nouns are Good; Verbs are bad 17
- 18. Keep Verbs out of your Base URLs
- 19. Keep Verbs out of your Base URLs
- 20. Singular Nouns or Plural Nouns ? 20
- 21. Singular Nouns or Plural Nouns ? • Foursquare – /checkins • GroupOn – /deals • Zappos – /Product
- 22. Singular Nouns or Plural Nouns ? • Avoid Mixed Model • Consistent • Prefer plural names – Reads more Easily – Intuitive
- 23. Concrete Names are better than abstract… 23
- 24. Concrete Names are better than abstract… • Abstractions is Not Always Meaningful • Depends on your scenario • Keep Number of Resources between 12 - 24
- 26. Complexity – Put it behind the ? • States that can be updated, changed, queried • Attributes associated with resource
- 27. Handling Errors… • Important piece of puzzle • Other Side of the API is a black box
- 28. Handling Errors – Best Practices • Granular Error Messages • Link to Documentation • Aligning Errors with Status Codes • Verbose as Possible
- 29. 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
- 30. 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
- 31. Versioning • Never Release without Version – /v1/dogs • Simple Ordinal Number • Atleast one version back • How long to maintain version ? – One Developer Cycle
- 32. Pagination & Partial Response • Pagination – Offset – Limit • Include Meta Data • Set Defaults • Partial Response – As optional Parameter – /dogs?fields=name,color,location
- 33. Support Multiple Formats • Support Multiple Formats of Data – JSON – XML • Default format ? • Syntax – Google : ?alt=json – FourSquare : /venue.json – Digg : Accept : application/json
- 34. 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
- 35. 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
- 36. Securing your APIs – OAuth 2.0
- 38. 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.
- 39. 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.
- 40. © 2013 Apigee Confidential – All Rights Reserved Common API Provider Concerns Protocol Transformation Mobile Optimization Versioning & Enrichment Security Mediation Traffic Management
- 41. © 2013 Apigee Confidential – All Rights Reserved Common API Provider Concerns Protocol Transformation Translate between REST to SOAP Translate between XML & JSON Mix HTTP and HTTPS Targets 2 Way SSL Target Security Manage External Data Sources
- 42. © 2013 Apigee Confidential – All Rights Reserved Common API Provider Concerns Mobile Optimization Compression & Decompression (gzip) Manage Pagination Streaming Payload Options
- 43. © 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
- 44. © 2013 Apigee Confidential – All Rights Reserved Common API Provider Concerns Security Mediation App Level Authentication User Level Authentication Custom Attributes/Key Translation Granular Analytics
- 45. © 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
- 47. Thank you
Notas del editor
- Ask Questions – Why do we need API Every day we make N -> API Calls Web , App , Devices etc etc..
- Main Point You can’t wait and see what happens, you will die. Script You could wait…. These are brands we have all known for many years but they chose to wait rather than adapt to the change. And when you lose momentum you lose significance, you die in the mind of customers. This is true for every business, no matter how big they are or how long they’ve been around. The change in consumer and employee expectations has happened fast, and if you don’t keep up, you risk losing business that you won’t be able to get back later.. The time to change is now. The longer you wait, the more disruptive the change will be when you no longer have a choice.
- Blood Vessels of Every Business Connects Business Process, Services , Data >>>>>>>>>>>>> Internal Teams, Customers, Open Developers Defacto Standard Connecting Entities in Eco System Glue in Digital Value Chain
- Main Point The value chain is at the heart of the solution Script These aren’t the kind of things that you can accomplish as an afterthought with some bolt-on solution. Only a solution that extends across the digital value chain will offer the necessary capabilities. Let me explain. Between the end user and the business’s back-end systems lie several important participants and pieces of technology, all of which need to work together seamlessly. Any and all apps, the developers who build them, the API they use, the API team—all of these things have requirements that need to be addressed. The right hand side is the hard part, that’s IT that is trying to do their best but the demands that are placed on them are ever increasing and the budgets are ever decreasing.
- Main Point The value chain is at the heart of the solution Script These aren’t the kind of things that you can accomplish as an afterthought with some bolt-on solution. Only a solution that extends across the digital value chain will offer the necessary capabilities. Let me explain. Between the end user and the business’s back-end systems lie several important participants and pieces of technology, all of which need to work together seamlessly. Any and all apps, the developers who build them, the API they use, the API team—all of these things have requirements that need to be addressed. The right hand side is the hard part, that’s IT that is trying to do their best but the demands that are placed on them are ever increasing and the budgets are ever decreasing.
- Main Point The value chain is at the heart of the solution Script These aren’t the kind of things that you can accomplish as an afterthought with some bolt-on solution. Only a solution that extends across the digital value chain will offer the necessary capabilities. Let me explain. Between the end user and the business’s back-end systems lie several important participants and pieces of technology, all of which need to work together seamlessly. Any and all apps, the developers who build them, the API they use, the API team—all of these things have requirements that need to be addressed. The right hand side is the hard part, that’s IT that is trying to do their best but the demands that are placed on them are ever increasing and the budgets are ever decreasing.
- Ask Questions – Why do we need API Every day we make N -> API Calls Web , App , Devices etc etc..
- - The success of an API design is measured by how quickly developers can get up to speed and start enjoying success using your API.
- The base URL is the most important design affordance of your API. A simple and intuitive base URL design makes using your API easy.
- Soon you have a long list of URLs and no consistent pattern making it difficult for developers to learn how to use your API.
- Use HTTP verbs to operate on the collections and elements. For our dog resources, we have two base URLs that use nouns as labels, and we can operate on them with HTTP verbs. Our HTTP verbs are POST, GET, PUT, and DELETE. (We think of them as mapping to the acronym, CRUD (Create-Read-Update-Delete).) With our two resources (/dogs and /dogs/1234) and the four HTTP verbs, we have a rich set of capability that's intuitive to the developer
- The base URL is the most important design affordance of your API. A simple and intuitive base URL design makes using your API easy.
- Being consistent allows developers to predict and guess the method calls as they learn to work with your API.
- An API that models everything at the highest level of abstraction - as /items or /assets in our example - loses the opportunity to paint a tangible picture for developers to know what they can do with this API. It is more compelling and useful to see the resources listed as blogs, videos, and news articles.
- An API that models everything at the highest level of abstraction - as /items or /assets in our example - loses the opportunity to paint a tangible picture for developers to know what they can do with this API. It is more compelling and useful to see the resources listed as blogs, videos, and news articles.
- An API that models everything at the highest level of abstraction - as /items or /assets in our example - loses the opportunity to paint a tangible picture for developers to know what they can do with this API. It is more compelling and useful to see the resources listed as blogs, videos, and news articles.
- An API that models everything at the highest level of abstraction - as /items or /assets in our example - loses the opportunity to paint a tangible picture for developers to know what they can do with this API. It is more compelling and useful to see the resources listed as blogs, videos, and news articles.
- There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So if you choose status codes that are not very common you will force application developers away from building their apps and over to Wikipedia to figure out what you're trying to tell them.
- There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So if you choose status codes that are not very common you will force application developers away from building their apps and over to Wikipedia to figure out what you're trying to tell them.
- There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So if you choose status codes that are not very common you will force application developers away from building their apps and over to Wikipedia to figure out what you're trying to tell them.
- There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So if you choose status codes that are not very common you will force application developers away from building their apps and over to Wikipedia to figure out what you're trying to tell them.
- There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So if you choose status codes that are not very common you will force application developers away from building their apps and over to Wikipedia to figure out what you're trying to tell them.
- JSON is winning out as the default format. JSON is the closest thing we have to universal language. Even if the back end is built in Ruby on Rails, PHP, Java, Python etc., most projects probably touch JavaScript for the front-end. It also has the advantage of being terse - less verbose than XML.
- Use the latest and greatest OAuth - OAuth 2.0 (as of this writing). It means that Web or mobile apps that expose APIs don’t have to share passwords. It allows the API provider to revoke tokens for an individual user, for an entire app, without requiring the user to change their original password. This is critical if a mobile device is compromised or if a rogue app is discovered.
- Use the latest and greatest OAuth - OAuth 2.0 (as of this writing). It means that Web or mobile apps that expose APIs don’t have to share passwords. It allows the API provider to revoke tokens for an individual user, for an entire app, without requiring the user to change their original password. This is critical if a mobile device is compromised or if a rogue app is discovered.
- Ask Questions – Why do we need API Every day we make N -> API Calls Web , App , Devices etc etc..
- Use the latest and greatest OAuth - OAuth 2.0 (as of this writing). It means that Web or mobile apps that expose APIs don’t have to share passwords. It allows the API provider to revoke tokens for an individual user, for an entire app, without requiring the user to change their original password. This is critical if a mobile device is compromised or if a rogue app is discovered.
- Use the latest and greatest OAuth - OAuth 2.0 (as of this writing). It means that Web or mobile apps that expose APIs don’t have to share passwords. It allows the API provider to revoke tokens for an individual user, for an entire app, without requiring the user to change their original password. This is critical if a mobile device is compromised or if a rogue app is discovered.
- Use the latest and greatest OAuth - OAuth 2.0 (as of this writing). It means that Web or mobile apps that expose APIs don’t have to share passwords. It allows the API provider to revoke tokens for an individual user, for an entire app, without requiring the user to change their original password. This is critical if a mobile device is compromised or if a rogue app is discovered.