Przejdź do treści

Przykłady requestów i odpowiedzi

Przykłady dla naszego API, zgodne z technical-conventions.md i założeniami REST API – Założenia v1.0 (pharmind XF): wersja w ścieżce /v1/, rzeczowniki w liczbie mnogiej, kebab-case w ścieżkach, snake_case w parametrach zapytań, camelCase w JSON, PATCH = tylko pola do zmiany, błędy w formacie Problem Details.

1. Odczyt zasobu (GET)

Request:

GET /v1/purchase-orders?user_id=123&start_date=2025-01-01 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Accept: application/json
ks-client: my-system

Response (200 OK):

{
  "id": "po-001",
  "orderNumber": "PO-2025-001",
  "status": "Open",
  "createdAt": "2025-01-15T10:00:00Z"
}

Pola w camelCase; parametry zapytań w snake_case. Konkretne zasoby i pola — zgodnie z api-contracts.md.

2. Utworzenie zasobu (POST)

Request:

POST /v1/purchase-orders HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "supplierId": "sup-001",
  "orderDate": "2025-01-15",
  "lineItems": [
    {
      "productId": "prod-001",
      "quantity": 10,
      "unitPrice": 99.50
    }
  ]
}

Response (201 Created):

{
  "id": "po-002",
  "orderNumber": "PO-2025-002",
  "status": "Open",
  "createdAt": "2025-01-15T11:00:00Z"
}

3. Częściowa aktualizacja zasobu (PATCH)

Request: Tylko pola do zmiany (prosty obiekt JSON).

PATCH /v1/invoices/inv-001 HTTP/1.1
Host: <base-url>
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

{
  "tags": ["tag1", "tag2"],
  "documentProcessingStatus": "Processed",
  "processingSystem": "ERP"
}

Response (200 OK): Zaktualizowany zasób (pola w camelCase) lub potwierdzenie — zgodnie z kontraktem.

4. Obsługa błędów (Problem Details)

Response (404 Not Found):

{
  "status": 404,
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Resource not found",
  "detail": "Purchase order 'po-999' could not be found",
  "instance": "/v1/purchase-orders/po-999"
}

Response (422 Unprocessable Entity):

{
  "status": 422,
  "type": "https://example.com/errors/validation",
  "title": "Validation error",
  "detail": "Quantity must be greater than zero",
  "instance": "/v1/purchase-orders"
}

Format zgodny z RFC 7807 Problem Details (status, type, title, detail, instance).

5. Statusy HTTP (skrót)

  • 200 OK — żądanie zakończone sukcesem.
  • 201 Created — zasób utworzony.
  • 202 Accepted — przyjęte do przetwarzania.
  • 204 No Content — brak body (np. po DELETE).
  • 400 Bad Request — nieprawidłowe dane.
  • 401 Unauthorized — wymagane logowanie.
  • 403 Forbidden — brak uprawnień.
  • 404 Not Found — zasób nie istnieje.
  • 409 Conflict — konflikt danych.
  • 422 Unprocessable Entity — błąd walidacji.
  • 429 Too Many Requests — przekroczony limit.
  • 500 Internal Server Error — błąd serwera.

6. Paginacja

Request (parametry w snake_case):

GET /v1/purchase-orders?page=1&page_size=20&order_by=createdAt&sort=desc HTTP/1.1

Response (200 OK):

{
  "items": [
    {
      "id": "po-001",
      "orderNumber": "PO-2025-001",
      "status": "Open"
    }
  ],
  "totalCount": 150,
  "nextPageToken": "eyJwYWdlIjoyfQ=="
}

Nazwy pól (np. nextPageToken, page_size) do ustalenia w konwencjach; pola w JSON w camelCase.

7. Zasób z Identifier i Coding (rozszerzalna identyfikacja, wzorowana na FHIR)

Modele mogą zawierać tablicę identifiers (identyfikatory z różnych systemów) oraz pola typu Coding / CodeableConcept (kody z systemów terminologicznych). Zgodnie z technical-conventions.md.

Response (200 OK) — np. zamówienie zakupu z identyfikatorami i typem dokumentu:

{
  "id": "po-001",
  "identifiers": [
    {
      "system": "https://api.example.com/identifiers/purchase-order",
      "value": "PO-2025-001",
      "use": "official"
    },
    {
      "system": "urn:supplier:erp:order-id",
      "value": "SUP-98765",
      "use": "secondary"
    }
  ],
  "orderNumber": "PO-2025-001",
  "documentType": {
    "coding": [
      {
        "system": "https://api.example.com/codes/document-type",
        "code": "PO",
        "display": "Purchase Order"
      }
    ],
    "text": "Purchase Order"
  },
  "status": {
    "coding": [
      {
        "system": "https://api.example.com/codes/order-status",
        "code": "open",
        "display": "Open"
      }
    ]
  },
  "createdAt": "2025-01-15T10:00:00Z"
}

identifiers — wielozakresowa identyfikacja (wewnętrzny numer, numer u dostawcy). documentType i status — CodeableConcept z tablicą coding (system, code, display) i opcjonalnym text.

Wszystkie przykłady odnoszą się do naszego API; po doprecyzowaniu kontraktów w api-contracts.md uzupełnić konkretnymi zasobami i polami.