Share
Embed
Transcript
33 slides
-
Johannes Pichler • living in Sandl, Austria • Web Developer
since 2006 • doing PHP, Go, .NET, Java • working @ Wimberger GmbH -
Outline for today • Designing your API • Implementation with
Laravel • Verification & Maintenance Phase of an API -
Elegant APIs? • Audience • Consistency • Predictability • Explicit
contracts • Evolvability -
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} -
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 -
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 -
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 -
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." } -
Pagination response meta { "data": [ { "id": 51, "name":
"Construction A" } ], "meta": { "page": 2, "size": 25, "total": 312, "total_pages": 13 } } -
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" ] } } -
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 -
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 • avoid server side caching • REST should
be stateless • for highly dynamic resources, hit rates are often low • 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 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 -
Key Takeaways • Specify your API before implementation • Secure
your API's data • Provide proper documentation to your clients • Be careful with introducing breaking changes -
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 *