Battle tested API Design - Laravel Edition (PHP.RUHR)

Transcript

1. Battle tested API Design Laravel Edition
2. Johannes Pichler Web Developer since 2006 PHP, Go, .NET, Java working @ Wimberger GmbH
3. Wimberger Gruppe company group with 8 members in the buildung industry 12 locations in Upper & lower Austra 820 employees
4. Outline API Design & Considerations API Implementation Verification & Maintenance
6. Consider the client(s)
7. REST Client-server architecture Statelessness Cacheability Layered system (Code on demand) Uniform interface https://en.wikipedia.org/wiki/REST
8. Requests based on resources use standard HTTP methods be as explicit as possible
9. Request Routing GET: /constructions GET: /constructions/{id} POST: /constructions PUT: /constructions/{id} DELETE: /constructions/{id}
10. Response GET /constructions/1 { "id": 1, "name": "Max Mustermann (4020 Linz)", "start_of_construction": "2023-09-28 10:30:00", "order_value": 10000 } PUT /constructions/1 { "message": "Construction saved." }
11. Adding structure GET /constructions/1 "data": { } { "id": 1, "name": "Max Mustermann (4020 Linz)", "start_of_construction": "2023-09-28 10:30:00", "order_value": 10000 }
12. Adding structure PUT /constructions/1 "data": { "id": 1, "name": "Max Mustermann (4020 Linz)", "start_of_construction": "2023-09-28 10:30:00", "order_value": 10000 }, "meta": { } { "message": "Construction saved." }
13. More response examples POST /constructions/1/index { "meta": { "id": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "message": "Construction indexing started." } }
14. More response examples - errors POST /constructions { "errors": { "name": [ "The name field is required" ], "order_value": [ "The order value field is required", "The order value field must be numeric" ] } }
15. Advices for structuring responses use groups for your data ( data , errors , meta ) determine response type based on the status code not on structure include resource data in the data section meta information in the meta section you may use a defined standard like JSON:API ` ` ` ` ` ` ` ` ` `
16. API security protect your endpoints use client specific tokens sensitive data with user tokens
17. API caching do not use server side caching REST should be stateless very low hit rates use ETags instead
18. Caching with ETags add an ETag Header to your responses this header value describes the state of your resource on subsequent requests include If-None-Match with the previous ETag header value if the resource version is still valid, the server responds with 304 not modified otherwise it sends a new response with a new ETag value ` ` ` ` ` ` ` ` ` `
19. API Specification describe your endpoints first also define edge cases make your specification testable document your APIs allow clients to understand your API endpoints
20. Open API - Model Construction: title: Construction type: object properties: id: type: integer description: Unique identifier for the given construction name: type: string description: the name of the construction start_of_construction: type: string description: the start date of the construction order_value: type: number format: date description: the construction's order value required: - id - name - start_of_construction
21. OpenAPI Paths paths: /constructions: get: summary: Retrieve a list of constructions tags: [] responses: '200': description: OK headers: {} content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Construction'
22. Implementation with Laravel List and detail endpoints protect them with an api token verify the API specification against the implementation
23. API Security Tips Client token based - custom implementation (store keys in config or database table) User token - use Laravel Sanctum or use existing OAuth2 implementation
24. Verification & Maintenance it’s all about metrics monitor which endpoints are used and which are not have useful error logging in place verify your assumptions already during development
25. Maintenance think about breaking changes use semantic versioning if necessary keep your API specification up to date
26. Summary Specify your API before implementation Secure your API’s data Provide documentation to your clients Be careful with introducing breaking changes
27. Thank you Slides: speakerdeck.com/fetzi Twitter: @fetzi_io