Crafting Elegant APIs with Laravel

Transcript

1. Crafting Elegant APIs with Laravel phpday - Verona 2024
2. Johannes Pichler • living in Sandl, Austria • Web Developer since 2006 • doing PHP, Go, .NET, Java • working @ Wimberger GmbH
3. Why am I talking about APIs?
4. APIS =
5. Outline for today • Designing your API • Implementation with Laravel • Verification & Maintenance Phase of an API
7. Consider the client(s)
8. Requests • based on resources • use standard HTTP methods • define a clear request schema that all your endpoints follow • use query parameters for filtering
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)", "order_value": 10000, "started_at": "2023-08-12 19:21:35", "finished_at": null } PUT /constructions/1 { "message": "Construction saved." }
11. Adding structure GET /constructions/1 { "data": { "id": 1, "name": "Max Mustermann (4020 Linz)", "order_value": 10000, "started_at": "2023-08-12 19:21:35", "finished_at": null } }
12. Adding structure PUT /constructions/1 { "data": { "id": 1, "name": "Max Mustermann (4020 Linz)", "order_value": 10000, "started_at": "2023-08-12 19:21:35", "finished_at": null }, "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) • define response type by the status code not by response structure • you may use a defined standard like JSON:API
16. Protecting your API endpoints • use client specific tokens by default • use user specific tokens to protect user data • Laravel Sanctum can help • if you really want to use OAuth2
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 • standard for describing APIs • general information • paths & models
21. 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 order_value: type: number format: date description: the construction's order value started_at: type: string description: the start date of the construction finished_at: type: string description: the end date of the construction required: - id - name - order_value
22. 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'
23. Implementation with Laravel • List and detail endpoints • protect them with an api token • verify the API specification against the 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. Take aways • Specify your API before implementation • Secure your API's data • Provide propper documentation to your clients • Be careful with introducing breaking changes
27. Resources • Laravel Open API Validation Library: kirschbaum- development/laravel-openapi-validator • Tool for editing Open API Specs: Stoplight Studio
28. Questions ? • speakerdeck.com/fetzi • Twitter / X: @fetzi_io Feedback