Network registry API

openapi: 3.0.0
info:
  title: network registry
  description: interface to network registry data at University of Helsinki
  contact:
    name: Niko Tyni et al.
    email: grp-tepa-netdata-api@helsinki.fi
  version: '1.0'
servers:
- url: https://gw.api.helsinki.fi/netdata
security:
- api_key: []
paths:
  /hosts:
    description: 'Operations not related to a specific existing host.

      '
    get:
      description: "List hosts matching the provided query parameters.\n \nOne or more parameters can\
        \ be specified, and they will be joined with an AND operator (in other words, the results will\
        \ match all the conditions.)\n \nThe parameters can contain the wildcards '*' (match any sequence\
        \ of zero or more characters) and '?' (match any one character.) Please note that '?' (the question\
        \ mark) may require URI escaping as '%3F' depending on your client.\n \nThe query parameters offer\
        \ only a limited set of attributes for filtering. The search endpoint provides the complete set.\n\
        \ \nContent authorization is based on API gateway plans with predefined access levels. Please\
        \ use the contact address if changes are required.\n"
      parameters:
      - name: nimi
        in: query
        description: match for host name
        required: false
        style: form
        explode: true
        schema:
          maxLength: 150
          type: string
        example: foo*.it
      - name: eth
        in: query
        description: match for host ethernet address
        required: false
        style: form
        explode: true
        schema:
          maxLength: 12
          type: string
        example: 00DEA?BEEF
      - name: ip
        in: query
        description: match for host IPv4 address
        required: false
        style: form
        explode: true
        schema:
          maxLength: 15
          type: string
        example: 128.214.0.*
      - name: ipv6
        in: query
        description: match for host IPv6 address
        required: false
        style: form
        explode: true
        schema:
          maxLength: 39
          type: string
        example: 2001:708:110:30::*
      responses:
        '200':
          description: JSON list of hosts matching the query
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostCollection'
        '400':
          description: Invalid request
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '500':
          description: Backend problem
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
    post:
      description: "Creates a new host in the registry.\n \nThe IPv4 and IPv6 addresses can be specified\
        \ with wildcards in the request, causing the service to assign a matching address.\n \nContent\
        \ authorization is based on API gateway plans with predefined access levels. Please use the contact\
        \ address if changes are required.\n"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Host'
              - $ref: '#/components/schemas/NewHostRequirements'
        required: true
      responses:
        '201':
          description: Successfully created new host
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
        '400':
          description: Invalid request
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '403':
          description: Insufficient access
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '500':
          description: Backend problem
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
    parameters:
    - $ref: '#/components/parameters/NetdataRef'
  /hosts/search:
    description: 'Full search for hosts in database.

      '
    post:
      description: "Create a search.\n \nThe request body must contain a JSON representation of the search\
        \ specification, which is a dictionary with the same keys as host objects. None of the keys is\
        \ mandatory, and the search will be construed as an AND operation over the specified ones.\n \n\
        The parameters can contain the wildcards '*' (match any sequence of zero or more characters) and\
        \ '?' (match any one character.)\n \nContent authorization is based on API gateway plans with\
        \ predefined access levels. Please use the contact address if changes are required.\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HostSearchSpecification'
        required: true
      responses:
        '201':
          description: Success
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostCollection'
        '400':
          description: Invalid request
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '500':
          description: Backend problem
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
    parameters:
    - $ref: '#/components/parameters/NetdataRef'
  /hosts/name/{nimi}:
    description: 'Manipulate a specific existing host in the registry.

      '
    get:
      description: "Returns information for a host in registry\n \nContent authorization is based on API\
        \ gateway plans with predefined access levels. Please use the contact address if changes are required.\n"
      responses:
        '200':
          description: JSON dict of the host attributes
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
        '400':
          description: Invalid request
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '403':
          description: Insufficient access
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '500':
          description: Backend problem
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
    put:
      description: "Replaces an existing host in the registry.\n \nAll existing attributes will be overwritten.\n\
        \ \nThe IPv4 and IPv6 addresses can be specified with wildcards in the request, causing the service\
        \ to assign a matching address.\n \nPlease note that this operation is *not* idempotent if the\
        \ host name is changed, or if wildcards are used in the IP address assignment (as they will probably\
        \ get new addresses in that case.)\n \nContent authorization is based on API gateway plans with\
        \ predefined access levels. Please use the contact address if changes are required.\n"
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/Host'
              - $ref: '#/components/schemas/NewHostRequirements'
        required: true
      responses:
        '200':
          description: Successfully replaced existing host
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
        '400':
          description: Invalid request
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '403':
          description: Insufficient access
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '500':
          description: Backend problem
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
    delete:
      description: "Deletes a host from the registry\n \nContent authorization is based on API gateway\
        \ plans with predefined access levels. Please use the contact address if changes are required.\n"
      responses:
        '204':
          description: Deletion successful
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '400':
          description: Invalid request
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '403':
          description: Insufficient access
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '500':
          description: Backend problem
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
    patch:
      description: "Modifies an existing host in the registry.\n \nThe existing host will retain any attributes\
        \ that are not provided in the request.\n \nThe IPv4 and IPv6 addresses can be specified with\
        \ wildcards in the request, causing the service to assign a matching address.\n \nContent authorization\
        \ is based on API gateway plans with predefined access levels. Please use the contact address\
        \ if changes are required.\n"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Host'
        required: true
      responses:
        '200':
          description: Successfully modified existing host
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Host'
        '400':
          description: Invalid request
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '403':
          description: Insufficient access
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
        '500':
          description: Backend problem
          headers:
            X-Netdata-Message:
              $ref: '#/components/headers/NetdataMessage'
    parameters:
    - name: nimi
      in: path
      description: The host name to be manipulated, without the '.helsinki.fi' domain part
      required: true
      style: simple
      explode: false
      schema:
        maxLength: 150
        type: string
      example: foobar.it
    - $ref: '#/components/parameters/NetdataRef'
components:
  schemas:
    NewHostRequirements:
      required:
      - laitos
      - nimi
      - rakennus
      - vh
      - vlan
      type: object
    Host:
      type: object
      properties:
        nimi:
          maxLength: 150
          type: string
          example: host.fe
        eth:
          maxLength: 12
          pattern: ^(-|[0-9a-fA-F]{12})$
          type: string
          nullable: true
        laitos:
          maxLength: 20
          type: string
        rakennus:
          maxLength: 20
          type: string
        vlan:
          maxLength: 40
          type: string
        vh:
          maxLength: 50
          type: string
          format: email
        ra:
          maxLength: 13
          pattern: ^\d{8}-\d{4}$
          type: string
          description: time of last change; value ignored on input
          format: YYYYMMDD-HHmm
          readOnly: true
          example: 20220812-1614
        ip:
          nullable: true
          oneOf:
          - maxLength: 1
            pattern: ^(\.|\*)?$
            type: string
            description: a single dot or asterisk means any address is fine
            example: .
          - maxLength: 1
            pattern: ^-$
            type: string
            description: a dash means no address and could be left out as well
            example: .
          - maxLength: 15
            pattern: ^[0-9*]{1,3}\.[0-9*]{1,3}\.[0-9*]{1,3}\.[0-9*]{1,3}$
            type: string
            example: 128.214.38.*
        ipv6:
          nullable: true
          oneOf:
          - maxLength: 1
            pattern: ^(\.|\*)?$
            type: string
            description: a single dot or asterisk means any address is fine
            example: .
          - maxLength: 1
            pattern: ^-$
            type: string
            description: a dash means no address and could be left out as well
            example: .
          - maxLength: 39
            pattern: ^[0-9a-f*:]+$
            type: string
            example: 2001:708:110:30::*
        laite:
          maxLength: 150
          type: string
        huone:
          maxLength: 150
          type: string
          nullable: true
        kayttaja:
          maxLength: 150
          type: string
          nullable: true
        dhcp:
          maxLength: 50
          type: string
          example: hki
        cname:
          maxLength: 150
          type: string
          nullable: true
          example: servername.it.helsinki.fi.
        flags:
          maxLength: 50
          type: string
          example: wol-aadalib
        routingscope:
          maxLength: 40
          type: string
          example: public
    HostCollection:
      type: array
      items:
        $ref: '#/components/schemas/Host'
    HostSearchSpecification:
      type: object
      properties:
        nimi:
          maxLength: 150
          type: string
          example: host*.fe
        eth:
          maxLength: 12
          type: string
          example: DEAD*BE?F
        laitos:
          maxLength: 20
          type: string
        rakennus:
          maxLength: 20
          type: string
        vlan:
          maxLength: 40
          type: string
        vh:
          maxLength: 50
          type: string
        ra:
          maxLength: 13
          type: string
        ip:
          maxLength: 15
          type: string
        ipv6:
          maxLength: 39
          type: string
        laite:
          maxLength: 150
          type: string
        huone:
          maxLength: 150
          type: string
        kayttaja:
          maxLength: 150
          type: string
        dhcp:
          maxLength: 50
          type: string
        cname:
          maxLength: 150
          type: string
        flags:
          maxLength: 50
          type: string
        routingscope:
          maxLength: 40
          type: string
  parameters:
    NetdataRef:
      name: X-Netdata-Reference
      in: header
      description: "Session or user identifier on the client system.\n \nAPI consumers are encouraged\
        \ to set this header to provide an audit trail for diagnostics. The contents will be logged on\
        \ the server for each request along with plan and subscription information.\n"
      required: false
      style: simple
      explode: false
      schema:
        maxLength: 50
        pattern: ^[-_+a-zA-Z0-9]+$
        type: string
  headers:
    NetdataMessage:
      description: Further information on the operation result
      style: simple
      explode: false
      schema:
        type: string
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header