Upgrade to PRO for Only $50/Year—Limited-Time Offer! 🔥

Crafting Elegant APIs with Laravel

Crafting Elegant APIs with Laravel

Johannes Pichler

May 16, 2024
Tweet

More Decks by Johannes Pichler

Other Decks in Programming

Transcript

  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. 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." }
  5. 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 } }
  6. 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." } }
  7. 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" ] } }
  8. 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
  9. 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
  10. API caching • do not use server side caching •

    REST should be stateless • very low hit rates • use ETags instead
  11. 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
  12. API Specification • describe your endpoints first • also define

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

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

    if necessary • keep your API specification up to date
  18. Take aways • Specify your API before implementation • Secure

    your API's data • Provide propper documentation to your clients • Be careful with introducing breaking changes