Share
Embed
Transcript
27 slides
-
Johannes Pichler Web Developer since 2006 PHP, Go, .NET, Java
working @ Wimberger GmbH -
Wimberger Gruppe company group with 8 members in the buildung
industry 12 locations in Upper & lower Austra 820 employees -
REST Client-server architecture Statelessness Cacheability Layered system (Code on demand)
Uniform interface https://en.wikipedia.org/wiki/REST -
Requests based on resources use standard HTTP methods be as
explicit as possible -
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)", "start_of_construction": "2023-09-28 10:30:00", "order_value": 10000 } PUT /constructions/1 { "message": "Construction saved." } -
Adding structure GET /constructions/1 "data": { } { "id": 1,
"name": "Max Mustermann (4020 Linz)", "start_of_construction": "2023-09-28 10:30:00", "order_value": 10000 } -
Adding structure PUT /constructions/1 "data": { "id": 1, "name": "Max
Mustermann (4020 Linz)", "start_of_construction": "2023-09-28 10:30:00", "order_value": 10000 }, "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 ) determine response type based on the status code not on structure include resource data in the data section meta information in the meta section you may use a defined standard like JSON:API ` ` ` ` ` ` ` ` ` ` -
API security protect your endpoints use client specific tokens sensitive
data with user tokens -
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 - 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 start_of_construction: type: string description: the start date of the construction order_value: type: number format: date description: the construction's order value required: - id - name - start_of_construction -
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 -
API Security Tips Client token based - custom implementation (store
keys in config or database table) User token - use Laravel Sanctum or use existing OAuth2 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 -
Summary Specify your API before implementation Secure your API’s data
Provide documentation to your clients Be careful with introducing breaking changes