API workshop by AWS and 3scale
3 likes3,114 views
This document outlines an API design and management workshop presented by Matthew McClean, Nicolas Grenié, and Manfred. The workshop covers API design best practices, AWS services like Amazon API Gateway and AWS Lambda, and 3scale API management. It includes sections on API design principles, AWS integration, and a customer case study of Rosette's API implementation with 3scale and AWS. Attendees will build and deploy an API using Amazon API Gateway, AWS Lambda, and 3scale for additional management features.
API workshop by AWS and 3scale
- 1. Designing and Managing Scalable APIs with AWS and 3scale Matthew McClean, @matthewmcclean Nicolas Grenié, @picsoung Manfred, @ManfredBo
- 2. Workshop logistics: bit.ly/API-workshop (GH repo) AWS and 3scale accounts: 3scale.net/aws-loft/ Prerequisites: ● AWS CLI ● Java 1.8 ● Maven ● Node.js ● Serverless.com framework
- 3. Content 1. API Design Best-Practices ○ API design principles ○ Practical tips ○ API definitions 2. AWS Services ○ Amazon API Gateway ○ AWS Lambda 3. 3scale API Management ○ Amazon API Gateway and 3scale integration ○ Customer Case Study: Rosette API
- 4. Content 1. API Design Best-Practices ○ API design principles ○ Practical tips ○ API definitions 2. AWS Services ○ Amazon API Gateway ○ AWS Lambda 3. 3scale API Management ○ Amazon API Gateway and 3scale integration ○ Customer Case Study: Rosette API
- 5. First API Design Principle Design the API with the developer in mind ...because developers are people too. Provide outstanding developer experience. Make developers successful ...and they make you successful. Img Src: http://dx.jeremiahlee.com/
- 6. API Design vs Resource Design Resources are nucleus of REST API design. A resource is an abstraction of a certain piece of information. The selection of resources depends on business domain and developer needs. Fine-grained vs coarse-grained selection of resources. APIs are operations on the resources.
- 7. Fine-grained vs coarse-grained API Design Simple vs flexible
- 8. Fine-grained vs coarse-grained API Design
- 9. Respect the HTTP standard
- 10. Verb Endpoint What for GET /book/{book_id} Retrieve details of a resource POST /book Create resource DELETE /book/{book_id} Delete resource PUT /book/{book_id} Update or create resource PATCH /book/{book_id} Update partial resource OPTIONS any URL return methods supported on this URL TRACE any URL Echoes CONNECT any URL Convert to TCP/IP tunnel HEAD /book/{book_id} Same as GET w/o response body
- 11. Design - HTTP code
- 12. Design - HTTP code
- 13. Design - HTTP code Source: https://http.cat/
- 14. Design - HTTP code
- 15. Design - HTTP code Custom error? Create your own. it should not be already defined in the spec 1xx Informational 2xx Success 3xx Redirection 4xx Client error 5xx Server error document it !!
- 16. Design - URLs Be explicit and intuitive GET /books - Retrieves a list of books GET /books/42 - Retrieves a specific book POST /books - Creates a new book PUT /books/42 - Updates book #42 PATCH /books/42 - Partially updates book #42 DELETE /books/42 - Deletes book #42 Singular or plural? keep it simple
- 17. Design - Versioning Following software analogy API should be versionated v1 , v1.1, v2.0 curl -X GET -H “X-API-VERSION: 1.1” http://mysite.com/api/books.json http://mysite.com/api/v1/books.json http://mysite.com/api/v1.1/books.json http://mysite.com/api/books.json?v=1.1
- 18. Design - Versioning How often are you going to change version? What about people already using your API? How many versions will you keep maintaining? What’s the roadmap?
- 19. Design - Versioning Don’t explicitly version your API non breaking changes no version = flexibility = win
- 20. API Definition Formats Support (API) design-first approaches Benefits: ● Language-agnostic API description ● Human- and machine-readable ● Understand capability without source code ● API discovery ● Interactive documentation Most common OpenAPI (born out of Swagger)
- 21. OpenAPI? Swagger? API description spec contains: ● Endpoints ● Parameters ● Expected inputs, outputs Machine readable: ● Automate testing ● Interactive documentation ● SDK generation Petstore Example
- 22. Supported by the industry
- 23. Tooling
- 24. Content 1. API Design Best-Practices ○ API design principles ○ Practical tips ○ API definitions 2. AWS Services ○ Amazon API Gateway ○ AWS Lambda 3. 3scale API Management ○ Amazon API Gateway and 3scale integration ○ Customer Case Study: Rosette API
- 25. AWS Part by Matthew...
- 26. Content 1. API Design Best-Practices ○ API design principles ○ Practical tips ○ API definitions 2. AWS Services ○ Amazon API Gateway ○ AWS Lambda 3. 3scale API Management ○ Amazon API Gateway and 3scale integration ○ Customer Case Study: Rosette API
- 28. 3scale and API Gateway Integration
- 30. How to achieve the Integration API deployed on API Gateway 3scale Custom Authorizer functions Cache API key to reduce latency framework To deploy Lambda functions SNS used for async update of cache
- 31. Serverless module for easy configuration Community framework to build, deploy and maintain Lambda functions Clone our repo and deploy functions on your own infrastructure serverless function create serverless function deploy
- 32. Hosted API Rollout with 3Scale Gregor Stewart, Basis Technology @olakrez
- 33. Rosette Users 33
- 35. 35
- 36. Design 36 Minimise effort to support Hosted and In a Box deployment ● Develop “in a box” first, add 3Scale to deliver Hosted ● From “RPC” to API: Entities ○ Three Components, represented by two Endpoints ○ Reduced to a single endpoint, with options ○ Common options across entity-centric endpoints ○ Separately documented option blob and output type to enable full control ● Explicit Versioning
- 37. 37 ● Server-based ● Custom NGINX ● Specialised Workers in Auto Scale Groups ● Integrated Caching and Queuing ● Security Focused Implementation
- 38. Challenges and Next Steps 38 ● Stateless to Stateful Endpoints ● Further “idiomatising” hosted implementation to AWS ○ Moving cache outside to service ○ Porting suitable functions to Lambda ■ LanguageID vs Entity Linking
- 39. Try it at: developer.rosette.com Gregor Stewart, Basis Technology @olakrez
- 40. Wrap-up Successful API starts with good API design. Lambda is an effective way to implement APIs. Amazon API Gateway adds crucial API security features. Serverless allows to configure and deploy Lambda easily. 3scale adds valuable API business features. AWS and 3scale provide a full complement API program management solution.
- 41. Lab overview 1. Create and deploy an API using the Amazon API Gateway and AWS Lambda 2. Integrate with 3scale to add API management features 3. Create tiered application plans with different API contracts (Optional) 4. Expose your API to developers with a developer portal and interactive API documentation (Optional) Github repo: bit.ly/API-workshop