Crafting Elegant APIs with Laravel

Transcript

1. Crafting Elegant APIs with Laravel DUTCH PHP CONFERENCE 2026
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. Elegant APIs? • Audience • Consistency • Predictability • Explicit contracts • Evolvability
8. Consider the client(s)
9. Requests • based on resources • use standard HTTP methods • define a clear request schema that all your endpoints follow • use query parameters for filtering
10. Request Routing GET: /constructions GET: /constructions/{id} POST: /constructions PUT: /constructions/{id} DELETE: /constructions/{id}
11. Request filtering • keep list endpoints focused on collections (GET / constructions) • support filtering via filter[...] • allow only whitelisted filter fields GET /constructions?filter[status]=active GET /constructions?filter[city]=Linz&filter[status]=active
12. Request sorting • support sorting via sort • use -field for descending order • validate sort fields against an allow-list GET /constructions?sort=started_at GET /constructions?sort=-started_at,name
13. Request pagination • use page[size] and page[number] • enforce defaults and maximum page size • keep pagination behavior consistent across collection endpoints GET /constructions?page[size]=25&page[number]=2
14. 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." }
15. Pagination response meta { "data": [ { "id": 51, "name": "Construction A" } ], "meta": { "page": 2, "size": 25, "total": 312, "total_pages": 13 } }
16. 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 } }
17. 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." } }
18. More response examples POST /constructions/1/index { "meta": { "id": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "message": "Construction indexing started." } }
19. 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" ] } }
20. Advice 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
21. 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
22. API caching • avoid server side caching • REST should be stateless • for highly dynamic resources, hit rates are often low • use ETags instead
23. 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
24. API Specification • describe your endpoints first • also define edge cases • make your specification testable • document your APIs • allow clients to understand your API endpoints
25. Open API • standard for describing APIs • general information • paths & models
26. 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 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
27. 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'
28. Implementation with Laravel • List and detail endpoints • protect them with an api token • verify the API specification against the implementation
29. 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
30. Maintenance • think about breaking changes • use semantic versioning if necessary • keep your API specification up to date
31. Key Takeaways • Specify your API before implementation • Secure your API's data • Provide proper documentation to your clients • Be careful with introducing breaking changes
32. Resources • Tool for editing Open API Specs: Stoplight Studio • Laravel Open API Validation Library: kirschbaum- development/laravel-openapi-validator • Laravel Query Builder: spatie/laravel-query-builder *
33. Questions? • speakerdeck.com/fetzi • Twitter / X: @fetzi_io Feedback