Crafting Elegant APIs with Laravel phpday - Verona 2024 

Johannes Pichler • living in Sandl, Austria • Web Developer since 2006 • doing PHP, Go, .NET, Java • working @ Wimberger GmbH 

Why am I talking about APIs? 

APIS = 

Outline for today • Designing your API • Implementation with Laravel • Verification & Maintenance Phase of an API 

No content

Consider the client(s) 

Requests • based on resources • use standard HTTP methods • define a clear request schema that all your endpoints follow • use query parameters for filtering 

Request Routing GET: /constructions GET: /constructions/{id} POST: /constructions PUT: /constructions/{id} DELETE: /constructions/{id} 

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." } 

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 } } 

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." } } 

More response examples POST /constructions/1/index { "meta": { "id": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "message": "Construction indexing started." } } 

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" ] } } 

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 

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 

API caching • do not use server side caching • REST should be stateless • very low hit rates • use ETags instead 

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 

API Specification • describe your endpoints first • also define edge cases • make your specification testable • document your APIs • allow clients to understand your API endpoints 

Open API • standard for describing APIs • general information • paths & models 

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 

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' 

Implementation with Laravel • List and detail endpoints • protect them with an api token • verify the API specification against the implementation 

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 

Maintenance • think about breaking changes • use semantic versioning if necessary • keep your API specification up to date 

Take aways • Specify your API before implementation • Secure your API's data • Provide propper documentation to your clients • Be careful with introducing breaking changes 

Resources • Laravel Open API Validation Library: kirschbaum- development/laravel-openapi-validator • Tool for editing Open API Specs: Stoplight Studio 

Questions ? • speakerdeck.com/fetzi • Twitter / X: @fetzi_io Feedback