sample-service.yaml

openapi: 3.0.3
info:
  title: Sample Service
  description: |
    Template for a request-response CAMARA API.

    Copy this file to your API repository's `code/API_definitions/` directory
    and adapt it to your API's resources and operations.

    This template demonstrates:
    - `$ref` to `../common/CAMARA_common.yaml` for shared schemas, error responses,
      parameters, headers, and security schemes
    - Two options for error responses:
      - Option A: Pure `$ref` for responses using only generic error codes
      - Option B: Local response definition extending generic errors with API-specific codes

    What follows are the mandatory CAMARA `info.description` content blocks, each bracketed by `<!-- CAMARA:MANDATORY:<name>:BEGIN/END -->` HTML comments (invisible in rendered documentation). The reference text lives in `code/common/info-description-templates.yaml` (synced from Commonalities); copy each block as-is from there. The Appendix A block (`identifying-device-from-access-token` shown below) is opt-in — swap to `identifying-phone-number-from-access-token` if your API uses `phoneNumber` as the subject identifier, or remove it if the access-token-subject pattern does not apply.

    > In case of conflict, the authoritative source (API Design Guide for §3.2.3 / §3.2.4 / Appendix A; the ICM authorization-and-authentication template) takes precedence. This disclaimer applies to the mandatory texts and to any other content in this sample.

    <!-- CAMARA:MANDATORY:identifying-device-from-access-token:BEGIN -->
    # Identifying the device from the access token

    This API requires the API consumer to identify a device as the subject of the API as follows:
    - When the API is invoked using a two-legged access token, the subject will be identified from the optional `device` object, which therefore MUST be provided.
    - When a three-legged access token is used however, this optional identifier MUST NOT be provided, as the subject will be uniquely identified from the access token.

    This approach simplifies API usage for API consumers using a three-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the authentication process.

    ## Error handling:

    - If the subject cannot be identified from the access token and the optional `device` object is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code.

    - If the subject can be identified from the access token and the optional `device` object is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device is identified by these two methods, as the server is unable to make this comparison.
    <!-- CAMARA:MANDATORY:identifying-device-from-access-token:END -->

    <!-- CAMARA:MANDATORY:authorization-and-authentication:BEGIN -->
    # Authorization and authentication

    The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile.

    The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation.

    In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design.
    <!-- CAMARA:MANDATORY:authorization-and-authentication:END -->

    <!-- CAMARA:MANDATORY:additional-error-responses:BEGIN -->
    # Additional CAMARA error responses

    The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

    Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.

    As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
    <!-- CAMARA:MANDATORY:additional-error-responses:END -->

    <!-- CAMARA:MANDATORY:request-body-strictness:BEGIN -->
    # Request body strictness

    This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response.
    <!-- CAMARA:MANDATORY:request-body-strictness:END -->
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: wip
  x-camara-commonalities: 0.8.0
externalDocs:
  description: Product documentation at CAMARA
  url: https://github.com/camaraproject/{apiRepository}
  # {apiRepository} MUST be replaced by the CAMARA API Repository name where the API specification is hosted.
servers:
  - url: "{apiRoot}/sample-service/vwip"
    variables:
      apiRoot:
        default: http://localhost:9091
        description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath`
tags:
  - name: Resources
    description: Operations on sample resources
security:
  - openId:
      - sample-service:resource:read
      - sample-service:resource:write
paths:
  /resources:
    post:
      tags:
        - Resources
      summary: Create a resource
      description: Creates a new resource with the provided properties.
      operationId: createResource
      parameters:
        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateResource"
      responses:
        "201":
          description: Resource created
          headers:
            x-correlator:
              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
        "400":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
        "401":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
        "403":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
        "409":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic409"
        "422":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic422"
        "429":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic429"
        "500":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
    get:
      tags:
        - Resources
      summary: List resources
      description: Returns a list of all resources accessible to the API consumer.
      operationId: listResources
      parameters:
        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
      responses:
        "200":
          description: List of resources
          headers:
            x-correlator:
              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                type: array
                minItems: 0
                maxItems: 1000
                items:
                  $ref: "#/components/schemas/Resource"
        "400":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
        "401":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
        "403":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
        "500":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
  /resources/{resourceId}:
    get:
      tags:
        - Resources
      summary: Get a resource by ID
      description: Returns the details of a specific resource identified by its ID.
      operationId: getResource
      parameters:
        - $ref: "#/components/parameters/ResourceId"
        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
      responses:
        "200":
          description: Resource details
          headers:
            x-correlator:
              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Resource"
        "400":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
        "401":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
        "403":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
        # Option A — pure $ref for responses using only generic error codes
        "404":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic404"
        "500":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
    delete:
      tags:
        - Resources
      summary: Delete a resource
      description: Deletes a specific resource identified by its ID.
      operationId: deleteResource
      parameters:
        - $ref: "#/components/parameters/ResourceId"
        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
      responses:
        "204":
          description: Resource deleted
          headers:
            x-correlator:
              $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
        "400":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic400"
        "401":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic401"
        "403":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic403"
        # Option B — local response extending generic errors with API-specific codes
        "404":
          $ref: "#/components/responses/ResourceNotFound404"
        "500":
          $ref: "../common/CAMARA_common.yaml#/components/responses/Generic500"
components:
  securitySchemes:
    openId:
      $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId"
  responses:
    # Option B example: API-specific error response extending generic error codes.
    # Use this pattern when an operation needs API-specific error codes in addition
    # to the generic ones defined in CAMARA_common.yaml.
    ResourceNotFound404:
      description: Resource not found
      headers:
        x-correlator:
          $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator"
      content:
        application/json:
          schema:
            allOf:
              - $ref: "../common/CAMARA_common.yaml#/components/schemas/ErrorInfo"
              - type: object
                properties:
                  status:
                    enum:
                      - 404
                  code:
                    enum:
                      - NOT_FOUND
                      - IDENTIFIER_NOT_FOUND
          examples:
            GENERIC_404_NOT_FOUND:
              description: The specified resource was not found
              value:
                status: 404
                code: NOT_FOUND
                message: The specified resource is not found.
            RESOURCE_404_IDENTIFIER_NOT_FOUND:
              description: API-specific — some identifier cannot be matched to a resource
              value:
                status: 404
                code: IDENTIFIER_NOT_FOUND
                message: Some of the provided identifiers are not found.
  parameters:
    ResourceId:
      name: resourceId
      in: path
      required: true
      description: Identifier of the resource to operate on
      schema:
        $ref: "#/components/schemas/ResourceId"
  schemas:
    ResourceId:
      type: string
      format: uuid
      maxLength: 36
      description: Unique identifier for the resource
    CreateResource:
      description: Properties for creating a new resource
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 128
          description: Human-readable name for the resource
        device:
          $ref: "../common/CAMARA_common.yaml#/components/schemas/Device"
    Resource:
      description: A resource managed by the API
      type: object
      required:
        - resourceId
        - name
      properties:
        resourceId:
          $ref: "#/components/schemas/ResourceId"
        name:
          type: string
          maxLength: 128
          description: Human-readable name for the resource
        device:
          $ref: "../common/CAMARA_common.yaml#/components/schemas/Device"