APIs are the cornerstone of Digital systems and platforms today. APIs find their use in several architecture patterns - be it SOA & Microservices or even modern UI apps. While being interactive, this talk would look closely into aspects of API design, which we tend to ignore or abuse frequently. This talk would also draw some perspectives on modern architectures like Serverless & GraphQL, and how we could employ new & powerful API patterns in our applications and systems. Key Takeaways => As developers and architects, you should walk away with some guidelines and best practices on API design => The talk would give a broad direction of the future of APIs and how future systems can be architected with new patterns

1. GET SOME REST
PRINCIPLES OF GOOD API DESIGN
MANOJ GANAPATHI, CHIEF ARCHITECT, CODEOPS

2. ABOUT ME
Manoj Ganapathi
Chief Architect, CodeOps Technologies
• More than 18+ years of IT experience
• Seasoned Architect with products and services experience
• Specialized in Cloud and DevOps
@manojgr
manojgr@gmail.com, manoj@codeops.tech
https://www.linkedin.com/in/manojg

3. AGENDA
• ABOUT APIS & REST
• API DESIGN BEST PRACTICES
• APIS IN THE SERVERLESS WORLD
• THE FUTURE – GRAPHQL

4. ABOUT APIS

5. WHY ARE APIS IMPORTANT?
• KEY FOR PLATFORMS – HELP SHAPE ECOSYSTEMS
• API DESIGN INFLUENCES APP EXPERIENCES
• APIS ARE FOR DEVELOPERS. THEY INFLUENCE DEVELOPER
PRODUCTIVITY
• APIS ARE A GATEWAY TO CLOUD-NATIVE ARCHITECTURES

6. MISCONCEPTIONS?
•A FAÇADE/LAYER TO BUSINESS LOGIC
•INTERNAL AND EXTERNAL APIS HAVE DIFFERENT
IMPORTANCE

7. WHAT IS REST?
• REPRESENTATIONAL STATE TRANSFER (REST) IS AN SOFTWARE ARCHITECTURAL STYLE THAT
DEFINES A SET OF CONSTRAINTS TO BE USED FOR CREATING WEB SERVICES.
• WEB SERVICES THAT CONFORM TO THE REST ARCHITECTURAL STYLE, TERMED RESTFUL WEB
SERVICES, PROVIDE INTEROPERABILITY BETWEEN COMPUTER SYSTEMS ON THE INTERNET.
• RESTFUL WEB SERVICES ALLOW THE REQUESTING SYSTEMS TO ACCESS AND MANIPULATE
TEXTUAL REPRESENTATIONS OF WEB RESOURCES BY USING A UNIFORM AND PREDEFINED SET
OF STATELESS OPERATIONS
-FROM WIKIPEDIA

8. REST BASICS
KEY ARCHITECTURAL PROPERTIES
• PERFORMANCE
• SCALABILITY
• SIMPLICITY
• MODIFIABILITY
• VISIBILITY
• PORTABILITY
ARCHITECTURAL CONSTRAINTS
• CLIENT-SERVER
• STATELESS
• CACHEABLE
• LAYERED SYSTEM
• UNIFORM INTERFACE
A far cry from the dark ages of SOAP, CORBA, RPC etc!

9. REST – UNIFORM INTERFACE
• IDENTIFICATION OF RESOURCES
• MANIPULATION OF RESOURCES
THROUGH REPRESENTATION
• SELF-DESCRIPTIVE MESSAGES
Resource as URIs
https://api.co/v1/orders/1
JSON, XML
HTTP GET, POST, PUT, DELETE
Mediatypes, cacheability, etc.

10. BEST PRACTICES

11. GENERAL BEST PRACTICES
• PREFER NOUNS TO VERBS
• /TICKETS/123 INSTEAD OF /GETTICKET/123
• VERBS CAN BE USED FOR ACTIONS /BOOKS/1/MARKASFAVORITE, /LOGIN
• PREFER PLURALS
/ORDERS, /CARS ETC.
• API PARAMETERS:
• PATH - REQUIRED, RESOURCE IDENTIFIER
• QUERY – OPTIONAL, QUERY COLLECTIONS
• BODY – RESOURCE-SPECIFIC LOGIC
• HEADER – GLOBAL, PLATFORM-WIDE

12. HTTP STATUS CODES ARE YOUR FRIENDS
• 1XX: HOLD-ON
• 2XX: HERE YOU GO
• 3XX: GO AWAY
• 4XX: YOU SCREWED UP
• 5XX: I SCREWED UP
• LEVERAGE ALL STATUS CODES ALONG WITH RELEVANT HEADERS TO COMMUNICATE
INTENT CLEARLY
• RETURNING 200 FOR ALL CONDITIONS IS A BAD PRACTICE

13. 2XX – HERE YOU GO!
Code Use Example
201 Created
Specify a location header pointing to the location of
newly created resource
POST /Orders …
HTTP/1.1 201 Created
Location: https://eshop.co/v2/orders/1
202 Accepted
Use: Request accepted but will be handled
asynchronously. No payload returned
POST /jobs
HTTP/1.1 202 Accepted
204 No Content
The resource was deleted and no payload is returned
DELETE /orders/654
HTTP/1.1 204 No content
206 Partial Content
A partial list of resources is returned, using pagination,
add a Link header to facilitate navigation
GET /orders?page=4
HTTP/1.1 206 Partial content
Link:
<http://eshop.co/orders?page=1>;rel="first
",
<http://eshop.co/orders?page=3>;rel="pre
v,<http://eshop.co/orders?page=5>;rel="ne
xt, <http://eshop.co/orders?page=9>;
rel="last"

14. OTHER CODES
Code Use
301 Moved permanently
302 Found
303 See other
304 Not modified
(used in caching)
307 Temporary Redirect
308 Permanent Redirect
Code Use
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method not allowed
429 Too many requests
Code Use
500 Internal Server Error
501 Not Implemented
503 Service Unavailable
509 Bandwidth Limit exceeded
405 Method not allowed
429 Too many requests

15. ERROR HANDLING (1/2)
• THEREFORE, APIS MUST RETURN A JSON ERROR REPRESENTATION THAT
CONFORMS TO THE ERROR.JSON

16. ERROR HANDLING (2/2)
Refer Error.json in the API Spec

17. VERSIONING
• MOST FREQUENT, IN THE URL:
HTTPS: //API. COM/V2/RESTAURANTS/1234
• CUSTOM HEADER: X-API-VERSION: 2
• LESS FREQUENT, WITH AN ACCEPT HEADER. CLIENTS DON’T HAVE TO CHANGE ENDPOINT,
BUT UPDATE HEADERS
GET /RESTAURANTS
ACCEPT: APPLICATION/VND.RESTAURANTS.V2+JSON

18. APIS IN THE SERVERLESS WORLD

19. TRADITIONAL ARCHITECTURE

20. MOVING TOWARDS RESILIENCE

21. GRAPHQL IN A NUTSHELL
• A QUERY LANGUAGE FOR YOUR API
• QUERY OR MUTATE EXACTLY WHAT YOU WANT
• MULTIPLE RESOURCES IN ONE REQUEST
• SUBSCRIPTION MODEL
• GRAPHQL APIS ARE ORGANIZED IN TERMS OF TYPES AND FIELDS, NOT
ENDPOINTS.
• ACCESS THE FULL CAPABILITIES OF YOUR DATA FROM A SINGLE ENDPOINT
(USUALLY).

22. Source: Hasura (https://www.slideshare.net/AWSUsersGroupBengalu/architecture-of-scalable-
and-resilient-apps-with-graphql-amazon-rds-and-aws-lambda )

23. ONE OF THE GRAPHQL IMPLEMENTATIONS - HASURA

24. QUESTIONS?

25. REFERENCES
• HTTPS://WWW.SLIDESHARE.NET/AWSUSERSGROUPBENGALU/ARCHITECTURE-OF-SCALABLE-AND-
RESILIENT-APPS-WITH-GRAPHQL-AMAZON-RDS-AND-AWS-LAMBDA
• THE NEVER-ENDING REST API DESIGN DEBATE
• HTTP://WWW.VINAYSAHNI.COM/BEST-PRACTICES-FOR-A-PRAGMATIC-RESTFUL-API
• HTTPS://GITHUB.COM/PAYPAL/API-STANDARDS/BLOB/MASTER/API-STYLE-GUIDE.MD
• HTTP://BLOG.OCTO.COM/EN/DESIGN-A-REST-API/
• HTTPS://GITHUB.COM/INTERAGENT/HTTP-API-DESIGN/BLOB/MASTER/SUMMARY.MD
• HTTP://SOOKOCHEFF.COM/POST/API/ON-CHOOSING-A-HYPERMEDIA-FORMAT/
• HTTP://WWW.TROYHUNT.COM/2014/02/YOUR-API-VERSIONING-IS-WRONG-WHICH-IS.HTML