APIs the right way

The goal of software engineering is to sustainably minimise lead time to create positive business impact, to ensure this and also get some good sleep at night, API developers need to understand the right way to build APIs. In these slides, I explain the key concepts and tools needed to achieve this.

Presented at the forLoop Ibadan: Learn, Engage and Grow that held June 3rd, 2017 at the Wennovation Hub.

Event Link: http://forloop.ng/events/forloop-ibadan-engage-learn-and-grow-j2u5ueys

Transcript

1. APIs the right way Adeyemi Olaoye @yemexx1 | adeyemiolaoye.me
2. Meet me Adeyemi Olaoye Ex Software Engineer Lead - Web Architecture and Integration adeyemiolaoye.me @yemexx1
3. I love singing I love travelling I love nature More me
4. APIs
5. What are APIs? Image source: www.playwellafrica.org “Application programmable interfaces” “universal plug” “socket” “service” “doorway”
6. REST APIs
7. The right way? “...an API must be easy to find and easy to register to use, and it must be clear how much the API can be trusted in mission-critical solutions.” - IBM “The goal of software development is to sustainably minimise lead time to create positive business impact” - Dan North “...and for the sake of good sleep at night” - Me
8. HTTP Methods
9. GET Vs POST ➔ Don’t POST https://example.com/customers/1/accounts?active=1 ➔ Do GET https://example.com/customers/1/accounts?active=1 • Use GET for retrieving data; bookmarkable resources with cacheable responses • Use POST for resources/endpoints that create, extend or annotate ➔ Don’t GET https://example.com/customers/1/beneficiaries?firstnam e=Ade&lastname=ola&account_number=1238213719 ➔ Do POST https://example.com/customers/1/accounts { "firstname":"Ade", "lastname":"ola", "account_number":1238213719 }
10. POST Vs PUT • Use PUT for idempotent operations ➔ Don’t POST https://example.com/accounts/2 ➔ Do PUT https://example.com/customers/1/accounts { "profile_image_url":"https://imgur.com/dhy325" } { "profile_image_url":"https://imgur.com/dhy325" }
11. Transformers
12. Transformers? { "name":"covfefe enterprises", "image_url":"https://example.com/dhy325.png", "status":"closed", "reviews_count":10, "store_tags":["press", "world"] } { "name": "covfefe enterprises", "image_url": "https://randomcdn.com/example/dhy325.png", "status": "closed", "reviews_count": 10, "store_tags": [ "press", "world" ], "products": { ... }, "reviews": { ... } } transformers
13. Benefits ➔ Data sideloading ➔ Reduce boilerplate code ➔ Separate concerns ➔ Minimise service time by using eager loaders
14. Samples //Task: load all products with their images and reviews //create transformer ... class ProductTransformer implements TransformerInterface { public function transform(Product $product) { return $product->toArray(); } public function includeImages(Product $product) foreach($product->images as $image){ $image->link = Commons::convertToCDNLink($image); } return $images->toArray(); } public function includeReviews(Product $product) { return $product->reviews->toArray(); } ... Full gist //fetch products and transform $products = Products::getProducts(); $products->eagerLoad(['Images', 'Reviews']); //transform data $transformerManager = new TransformerManager(); $collection = $tranformerManager->createCollection($products, new ProductTransformer()); //convert collection to array or prefferred output $productsData = $collection->createData()->toArray(); //ship it!
15. Implementation PHP - http://fractal.thephpleague.com/ Node - https://www.npmjs.com/package/node-json-transform Java - org.apache.commons.collections4.Transformer
16. Responses
17. Formats
18. Consistency ➔ Don’t GET https://example.com/stores/2 ➔ Do GET https://example.com/stores/1 { "name":"covfefe enterprises", "image_url":"https://imgur.com/dhy325", "status":"closed", "reviews_count":10, "store_tags":["press", "world"] } { "Name":"covfefe enterprises", "imageUrl":"https://imgur.com/dhy325", "status":"closed", "reviews_count":10, "store tags":["press", "world"] }
19. Documentation
20. Checklist - Readme.io’s checklist Image source: www.api2cart.com
21. Checklist Image source: www.api2cart.com
22. Checklist Image source: www.api2cart.com
23. Testing
24. Frameworks Unit - JUnit - PHPUnit - Mocha Functional/Acceptance - Dredd - Codeception - Should.js
25. Beautiful APIs http://docs.localytics.com/dev/query-api.html#query-api https://developer.paypal.com/docs/ https://www.twilio.com/docs/api https://developers.facebook.com/docs/graph-api/
26. References https://www.slideshare.net/mattbiehl/digital-business-models-for-apis?ref=http://api-university.co m/blog/what-is-the-business-model-of-your-api/ https://www.programmableweb.com/news/what-api-exactly/analysis/2015/12/03 https://tools.ietf.org/html/rfc2616 https://speakerdeck.com/tdpauw/xp2017-feature-branching-is-evil APIs for dummies
27. Questions?