Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Crafting Elegant APIs with Laravel

Crafting Elegant APIs with Laravel

Johannes Pichler

March 13, 2026

Transcript

33 slides
  1. Johannes Pichler • living in Sandl, Austria • Web Developer

    since 2006 • doing PHP, Go, .NET, Java • working @ Wimberger GmbH
  2. Outline for today • Designing your API • Implementation with

    Laravel • Verification & Maintenance Phase of an API
  3. Requests • based on resources • use standard HTTP methods

    • define a clear request schema that all your endpoints follow • use query parameters for filtering
  4. 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
  5. 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
  6. 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
  7. 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." }
  8. Pagination response meta { "data": [ { "id": 51, "name":

    "Construction A" } ], "meta": { "page": 2, "size": 25, "total": 312, "total_pages": 13 } }
  9. 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 } }
  10. 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." } }
  11. 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" ] } }
  12. 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
  13. 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
  14. API caching • avoid server side caching • REST should

    be stateless • for highly dynamic resources, hit rates are often low • use ETags instead
  15. 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
  16. API Specification • describe your endpoints first • also define

    edge cases • make your specification testable • document your APIs • allow clients to understand your API endpoints
  17. 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
  18. 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'
  19. Implementation with Laravel • List and detail endpoints • protect

    them with an api token • verify the API specification against the implementation
  20. 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
  21. Maintenance • think about breaking changes • use semantic versioning

    if necessary • keep your API specification up to date
  22. Key Takeaways • Specify your API before implementation • Secure

    your API's data • Provide proper documentation to your clients • Be careful with introducing breaking changes
  23. 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 *

More Decks by Johannes Pichler

Other Decks in Programming