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.

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

27. 3scale API Management

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

34. What Rosette Does
34

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

42. Contact Details
Nico
nicolas@3scale.net
@picsoung
www.3scale.net
Manfred
manfred@3scale.net
@ManfredBo
bit.ly/API-workshop