Recipes for API Ninjas
•
1 gostou•421 visualizações
Main focus of the talk is to communicate some key concepts of designing/implementing APIs based on an enterprise grade API Standards and Guidelines. We will try to handcraft few API recipes(i.e. implementation design) with real-life examples mixed with a live coding session. While working on each recipe, we will delve into the rationale behind design decisions and best practices. We believe that these concepts will help a developer build a comprehensive API solution from scratch.
Recomendados
Recomendados
Mais conteúdo relacionado
Mais procurados
Mais procurados (20)
Semelhante a Recipes for API Ninjas
Semelhante a Recipes for API Ninjas (20)
Mais de Nordic APIs
Mais de Nordic APIs (20)
Último
Último (20)
Recipes for API Ninjas
- 1. Sandip Dhummad Director Technology Architecture S&P Global Ratings DevSecOps Communities of Practice Lead Recipes for API Ninjas Amit Patel Sr Cloud Architect S&P Global Ratings API Communities of Practice Lead https://www.linkedin.com/in/sandipdhummad/ @sdhummad https://www.linkedin.com/in/avpatel257 @two57
- 2. Agenda Recipes Recipe #1 – Build RESTful service Recipe #2 – Input data validation Recipe #3 – Fetch selected fields only Recipe #4 – Filter response Recipe #5 – Request results in paginated fashion Recipe #6 – Cache API result Recipe #7 – Compress API result Luncheon – Demo of an API using relational DB supporting all recipes 2
- 3. APIs Everywhere 3 01 API can attract blockbuster complements 02 APIs are the windows to new ecosystems API First• Over 19,000-API mark in January of 2018 • Since January of 2014, an average of more than 2,000 APIs have been added per year
- 4. API First Strategy 4 But….. Will it make my APIs a hit in market like Netflix, Facebook, Twitter, Google APIs? Important architectural/technical aspects for building scalable, reliable, light weight API What makes APIs more consumer friendly and easy to use???
- 5. API – Culinary Art 5 Customers Cook Pizza Soup Taco Fries Requests Customer API with several features(i.e. Recipes) Business User API Ninja Tries to implement API with requested features using various techniques that we are going to discuss today Comprehensive API Chef
- 6. Recipe #1 Build RESTful service 6 Build Restful API for managing customer information. A customer can have one or many contacts. A Contact can have one or many addresses Business User API Ninja URI Action Mapping • URI is the identity of an API like one’s name. Think twice before finalize the resource name URI • Follow below 4 resource archetypes • Document – Singular concept, represents fields with values or links. E.g. /customers/john • Collection – Server managed directory of resources E.g. /customers • Store - Client managed resource repo. E.g. PUT /customers/john • Controller - Procedural concept like executable function. E.g. /customers/john/credit-check Action Mapping • Create –> POST, Read –> GET, Update –> PUT, Delete –> DELETE Guidelines
- 7. Recipe #1 Build RESTful service 7 Build Restful API for managing customer information. A customer can have one or many contacts. A Contact can have one or many addresses Business User API Ninja URI Action Mapping • Standard naming conventions makes API more intuitive • Good API documentations plays very important role in API adoption. Don’t neglect them. Naming Conventions API Docs URI • All lower case • Separate words by ‘-’, e.g. /credit-check • Archetype mapping • Document names -> Singular Noun • Collection names -> Plural Noun • Store names -> Plural Noun • Controller names -> Verb or Verb phrase Query Param • Either follow the same pattern as URI or define it based on data binding supported by backend language(s), e.g. ?fields={firstName, lastName} API Docs • API docs with inline test/try capability Guidelines
- 8. Recipe #2 Input data validation 8 Length Check Null Check Pattern Check Input Sanitization Make sure that customer provides first name, size of name fields is not more than 80, provides valid email/phone number etc. Business User Other API Ninja • Input data validation is important vehicle for API security Input Data Validation • Leverage cross cutting aspects for data validation for avoiding boiler plate code • Use data binding/validation frameworks like Bean Validation, Hibernate Validations etc. for Java applications • Leverage consistent error handling mechanism for all your APIs Input Sanitization • Prevents attacks like XSS, SQL Injection, Header Bomb etc. • Use API gateway or a cross cutting concern for input sanitization Guidelines
- 9. Recipe #3 Fetch selected fields only 9 Approach Controller Resource Versioning • API Consumer knows how to use API for their applications, let’s put them in driving seat. Also implement similar high performant API with partial response for mobile clients Business User API Ninja Why Partial Response Capability Needed? • To avoid over-fetching or under-fetching problems • Helps remove service sprawl and version sprawl issue Methods - Service Provider vs Consumer • Service provider defines what should a domain object look like for a given resource • Depending on the client application need, consumer knows the shape of an object needed better than service provider Approaches 1. Controller Resource • TShirt sizing or templatizing response leads to service sprawl issue. For e.g. /customers/1/lite • Leads to Service sprawl issues 2. Versioning • Never ever use versioning for shaping response object • Leads to version sprawl issues
- 10. Recipe #3 Fetch selected fields only 10 Approach Controller Resource Identifying Path Optional Fields Nested Fields Mandatory Fields Field Selector • API Consumer knows how to use API for their applications, let’s put them in driving seat. Also implement similar high performant API with partial response for mobile clients Business User API Ninja Approaches 3. Leverage Identifying Path • Add form factor in URI. E.g. /mobile/customers/1 • If different field list provided based on dimensions other than form factor like client, product etc. then add them in the path. E.g. /premium/customers/1 • Leads to Service sprawl issues 4. Field Selector • Ability to define list of fields to be retrieved by API consumer. E.g. /customers/1?fields=firstName,lastName • Need to make sure that mandatory fields like id are always provided as they are needed for following operations • Support for Nested Object field is a big plus • This method provides much control to consumers without causing service/version sprawl • Downside of this approach is that field name proliferation to client code Versioning
- 11. Recipe #4 Filter response 11 Approach Support for Query Operators Type binding Multi Datastore SupportController Resource By the way I also need an ability to query the response like select all customers living in NYC. Take a look at Salesforce API. Business User API Ninja Why Response Filtering is Needed? • Consumer knows what needs to be filtered based on application context • To avoid over-fetching or under-fetching problems • Helps remove service sprawl and version sprawl issue Approaches 1. Controller Resource • Controllers supporting predefined filters. E.g. /customers/nyc • Can support very limited filtering needs • Leads to Service sprawl issues 2. Filtering through Query Expression • Filtering response through query expression provides lots of flexibilities. E.g. /customers?query=firstName==Jonh* • Queries can be supplied either in request body or through query parameter • Inner architecture is complex – data type binding, operators, federation to multi data sources etc. • Leverage spec like FIQL/RSQL, Elastic Search, GraphQL, OData etc. for Query language • API Consumer would love to play with your API, if they support simple filtering mechanisms. This differentiating capability would empower your API consumers for building newer apps
- 12. 12 Looks like API is too slow and BTW why are your returning all records at once? Business User API Ninja • Request that returns multiple items should be paginated Without pagination, a simple search could return millions or even billions of hits causing extraneous network traffic. Offset Pagination • simplest form of paging • Easiest to implement • Not performant for large offset values • Not reliable when new items are inserted to DB Keyset-based/Continuation Token: • Faster and more reliable • Scalability, reliability and efficiency depends on the approach • continuation token points to the last element of the current page. It is passed back to the server in order to retrieve the next page • Link for next page (HATEOS) Guidelines Approach DB Level Pagination Client Side Pagination Application Level Pagination Recipe #5 Pagination
- 13. 13 Looks like API is too slow? Business User API Ninja • Cache settings and cache management should be carefully done matching application needs. • Client side Caching • caching policy via the Cache-Control HTTP header • Server side cache • Memcached • Redis • Leverage external cache, preferably distributed cache for API result caching • Prefer to do method level caching for API result • Add proper cache expiration headers in the API results Guidelines Approach DB Level Caching Client Side Caching Application Level Caching Cache Options Local Cache Distributed Cache Recipe #6 Cache API result
- 14. 14 Looks like API returns huge payload and is slow? Business User API Ninja • Its a good practice to compress the service responses especially for the methods returning collection of objects Compression Algorithm • Leverage widely adopted standard compression algorithm like Gzip Framework Support • Use a method level custom annotation implemented(@Compress) in the services framework, wherever compression of API result is required Guidelines Approach Shared Functionality Browser Friendly Compression Algo Toggle ON/OFF Recipe #7 Compression
- 15. Luncheon 15
- 16. Demo of an API using relational DB supporting all recipes 16 The reference implementation of Customer API connecting to relational DB(Mysql/H2) supports following features: • CRUD operations • Input data validation • Fetch selected fields only • Filter response by expression • Compress API result
- 17. 17 Let’s pray to Demo God -:Demo Time:- https://github.com/avpatel257/nordic-apis-2019
- 18. 18 Thank You!!
- 19. 19 Icon(s) made by Freepik from www.flaticon.com References REST API Design Rulebook by Mark Masse https://www.programmableweb.com/news/research-shows-interest-providing-apis-still- high/research/2018/02/23 https://hbr.org/2015/01/the-strategic-value-of-apis Programmable Web - Harvard Business Review Article - Important Information Credit https://github.com/avpatel257/nordic-apis-2019 Sample Source Code