Entur Items API

openapi: 3.2.0
info:
  title: Example Service Items API
  version: 1.0.0
  description: A long and descriptive description
  termsOfService: https://developer.entur.org/terms-of-service
  contact:
    name: API Support
    url: https://entur.no
    email: support@entur.no
  x-entur-metadata:
    id: example
    owner: team-api
    audience: partner
servers:
- url: https://api.entur.io/product/v1
  description: Production
- url: https://api.staging.entur.io/product/v1
  description: Staging
tags:
- name: Items
paths:
  /items:
    get:
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/Page-Size'
      - name: status
        description: Filters items to return on status
        in: query
        schema:
          type: string
        example: completed
      summary: Get items
      description: Get items matching a status filter, with pagination support.
      operationId: getItems
      responses:
        '200':
          description: Get items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Items'
      x-entur-permissions:
        value: items:les
    post:
      tags:
      - Items
      security:
      - jwt: []
      summary: Create an item
      description: Create a new item, given in request body.
      operationId: createItem
      requestBody:
        description: Item to create
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
      x-entur-permissions:
        description: You need access to read organisations, and create items.
        value:
          all:
          - organisations:les
          - any:
            - items:opprett
            - items-global:opprett
  /items/{itemId}:
    parameters:
    - $ref: '#/components/parameters/Item-Id'
    get:
      tags:
      - Items
      summary: Get an item
      description: Get an item with given id.
      operationId: getItem
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
    put:
      tags:
      - Items
      security:
      - jwt: []
      summary: Update an item
      description: Update an item according to given item request body.
      operationId: updateItem
      requestBody:
        description: Item to update
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Item'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
components:
  schemas:
    Items:
      type: array
      items:
        $ref: '#/components/schemas/Item'
      example:
      - id: '100'
        name: Item 100
      - id: '101'
        name: Item 101
    Problem:
      type: object
      properties:
        type:
          type: string
          example: https://example.com/probs/invalid-parameter
        title:
          type: string
          example: Invalid parameter
        detail:
          type: string
          example: The parameter 'exampleParameter' is invalid.
        status:
          type: integer
          example: 400
      example:
        type: https://example.com/probs/invalid-parameter
        title: Invalid parameter
        detail: The parameter 'exampleParameter' is invalid.
        status: 400
    Item:
      type: object
      properties:
        id:
          type: string
          example: '100'
        name:
          type: string
          example: Item 100
      examples:
      - id: '100'
        name: Item 100
      - id: '100'
        name: null
  parameters:
    Page:
      description: Results page you want to retrieve (0..N)
      in: query
      required: true
      name: page
      schema:
        type: integer
        example: 0
    Page-Size:
      description: Number of records per page.
      in: query
      name: size
      schema:
        type: integer
        example: 20
    Item-Id:
      name: itemId
      description: The item ID.
      in: path
      required: true
      schema:
        type: string
      example: '100'
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT