Battle tested API design

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.

E44317a06f6ff5fec214d3f54f7ba432?s=128

Johannes Pichler

August 30, 2019
Tweet

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
  5. None
  6. The API Waterfall

  7. None
  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
  19. None
  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