University of Helsinki Hosts API

openapi: 3.2.0
info:
  title: network registry Hosts API
  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: []
tags:
- name: Hosts
paths:
  /hosts:
    description: 'Operations not related to a specific existing host.

      '
    parameters:
    - $ref: '#/components/parameters/NetdataRef'
    get:
      description: 'List hosts matching the provided query parameters.


        One 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.)


        The 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.


        The query parameters offer only a limited set of attributes for filtering. The search endpoint provides the complete set.


        Content authorization is based on API gateway plans with predefined access levels. Please use the contact address if changes are required.'
      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'
      tags:
      - Hosts
      summary: Get hosts
      x-summary-source: derived
      operationId: getHosts
      x-operation-id-source: derived
    post:
      description: 'Creates a new host in the registry.


        The IPv4 and IPv6 addresses can be specified with wildcards in the request, causing the service to assign a matching address.


        Content authorization is based on API gateway plans with predefined access levels. Please use the contact address if changes are required.'
      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'
      tags:
      - Hosts
      summary: Create hosts
      x-summary-source: derived
      operationId: postHosts
      x-operation-id-source: derived
  /hosts/search:
    description: 'Full search for hosts in database.

      '
    parameters:
    - $ref: '#/components/parameters/NetdataRef'
    post:
      description: 'Create a search.


        The 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.


        The parameters can contain the wildcards ''*'' (match any sequence of zero or more characters) and ''?'' (match any one character.)


        Content authorization is based on API gateway plans with predefined access levels. Please use the contact address if changes are required.'
      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'
      tags:
      - Hosts
      summary: Create hosts search
      x-summary-source: derived
      operationId: postHostsSearch
      x-operation-id-source: derived
  /hosts/name/{nimi}:
    description: 'Manipulate a specific existing host in the registry.

      '
    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'
    get:
      description: 'Returns information for a host in registry


        Content authorization is based on API gateway plans with predefined access levels. Please use the contact address if changes are required.'
      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'
      tags:
      - Hosts
      summary: Get hosts name by nimi
      x-summary-source: derived
      operationId: getHostsNameByNimi
      x-operation-id-source: derived
    put:
      description: 'Replaces an existing host in the registry.


        All existing attributes will be overwritten.


        The IPv4 and IPv6 addresses can be specified with wildcards in the request, causing the service to assign a matching address.


        Please 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.)


        Content authorization is based on API gateway plans with predefined access levels. Please use the contact address if changes are required.'
      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'
      tags:
      - Hosts
      summary: Replace hosts name by nimi
      x-summary-source: derived
      operationId: putHostsNameByNimi
      x-operation-id-source: derived
    delete:
      description: 'Deletes a host from the registry


        Content authorization is based on API gateway plans with predefined access levels. Please use the contact address if changes are required.'
      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'
      tags:
      - Hosts
      summary: Delete hosts name by nimi
      x-summary-source: derived
      operationId: deleteHostsNameByNimi
      x-operation-id-source: derived
    patch:
      description: 'Modifies an existing host in the registry.


        The existing host will retain any attributes that are not provided in the request.


        The IPv4 and IPv6 addresses can be specified with wildcards in the request, causing the service to assign a matching address.


        Content authorization is based on API gateway plans with predefined access levels. Please use the contact address if changes are required.'
      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'
      tags:
      - Hosts
      summary: Update hosts name by nimi
      x-summary-source: derived
      operationId: patchHostsNameByNimi
      x-operation-id-source: derived
components:
  schemas:
    NewHostRequirements:
      required:
      - laitos
      - nimi
      - rakennus
      - vh
      - vlan
      type: object
    HostCollection:
      type: array
      items:
        $ref: '#/components/schemas/Host'
    Host:
      type: object
      properties:
        nimi:
          maxLength: 150
          type: string
          example: host.fe
        eth:
          maxLength: 12
          pattern: ^(-|[0-9a-fA-F]{12})$
          type:
          - string
          - 'null'
        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:
          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:
          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
          - 'null'
        kayttaja:
          maxLength: 150
          type:
          - string
          - 'null'
        dhcp:
          maxLength: 50
          type: string
          example: hki
        cname:
          maxLength: 150
          type:
          - string
          - 'null'
          example: servername.it.helsinki.fi.
        flags:
          maxLength: 50
          type: string
          example: wol-aadalib
        routingscope:
          maxLength: 40
          type: string
          example: public
    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