Battle tested API design

Well designed and performant API's are key aspects of good and reliable application systems.

Especially when kicking of an API system it is really hard to setup and define all boundaries that are necessary to build a futureproof API. Changes later on can be time consuming and of course expensive.

Therefore it is extremely important to plan the API design beforehand and to use best practices and patterns from the industry.

In this session I will guide the listeners through the creation process of an API and will introduce and explain all important parts that constitute a battle tested and robust API. Things like middleware layers, security tokens are only some key points that will be presented on stage.

Transcript

1. Ba#le tested API design Web Summer Camp 2019
2. Johannes Pichler • Web Developer since 2006 • PHP, .NET, Java • Lead Developer @ karriere.at
3. karriere.at • biggest job platform in Austria • ~ 150 employees • ~ 40 developers
4. Outline • API design in general • Slim framework and Laravel Eloquent • Exercises Middlewares • Exercises json:api responses • Exercise json:api hydrators
6. The API Waterfall
8. The API Waterfall • Requirements & Planning • Implementation • Verification & Maintenance
9. Requirements & Planning
10. Consider the client(s)
11. Routing • based on resources • use standard HTTP methods • be as explicit as possible
12. Routing GET: /users GET: /users/{id} POST: /users PATCH: /users/{id} DELETE: /users/{id}
13. Routing - API Versioning • frequency of endpoint changes • handling of breaking changes • use semantic versioning • use only major version in URLs
14. Response format • no custom response format • use a defined standard •JSON:API •HAL
15. Authorization • use specific client tokens • add access tokens for sensitive endpoints
16. API Specification • use an API client like Postman • define your endpoints with edge cases • make your specification testable
17. Selecting a Framework • PSR-7 HTTP message interface •ServerRequestInterface •ResponseInterface • Middleware support (PSR-15) • dependency injection • configuration management
18. Middlewares • used for standard API logic • can be used globally, per route or per route group • easy way to intercept the request lifecycle
20. Verification & Maintenance
21. Verification • it's all about metrics • have useful error logging in place • verify your assumptions during development
22. Maintenance • be careful with breaking changes • stick to semantic versioning • keep your API specification up to date
23. Exercise Information
24. HTTP Handlers (PSR-15) interface RequestHandlerInterface { public function handle( ServerRequestInterface $request ): ResponseInterface; }
25. Middlewares (PSR-7) interface MiddlewareInterface { public function process( ServerRequestInterface $request, RequestHandlerInterface $handler ): ResponseInterface; }
26. json:api format { "data": { "type": "product", "id": "1", "attributes": { "name": "Product 1", "price": 1000 } } }
27. json:api relationships { "data": { "type": "product", "id": "1", "attributes": { "name": "Product 1", "price": 1000 }, "relationships": { "product-group": { "data": { "type": "product-group", "id": "1" } } } } }
28. Resources • https://github.com/fetzi/websummercamp-api-design • https://www.slimframework.com/ • https://jsonapi.org/
29. Questions?
30. THANKS @fetzi_io