CT#102

openapi: 3.0.0

info:

  title: PINServer PAS Registration_API

  version: 1.0.0-alpha.1

  description: |

    API for PAS registration to PIN server.  

    © 2023, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  

    All rights reserved.

externalDocs:

  description: >

    3GPP TS 29.583; Application layer support for Personal IoT Network (PINAPP);

    Personal IoT Network (PIN) Server Services; Stage 3.

  url: 'http://www.3gpp.org/ftp/Specs/archive/29_series/29.583/'

security:

  - {}

  - oAuth2ClientCredentials: []

servers:

  - url: '{apiRoot}/ppinserver-as-registration/v1'

    variables:

      apiRoot:

        default: https://example.com

        description: apiRoot as defined in clause 6.3 of 3GPP TS 29.583.

paths:

  /registrations:

    post:

      summary: Create a new PAS Registration

      operationId: CreatePASRegistration

      tags:

        - PAS Registrations (Collection)

      description: Register a new PAS at the PIN Server.

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/PASRegistration'

      responses:

        '201':

          description: PAS information is registered successfully at PIN server.

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/PASRegistration'

          headers:

            Location:

              description: 'Contains the URI of the newly created resource'

              required: true

              schema:

                type: string

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '411':

          $ref: 'TS29122_CommonData.yaml#/components/responses/411'

        '413':

          $ref: 'TS29122_CommonData.yaml#/components/responses/413'

        '415':

          $ref: 'TS29122_CommonData.yaml#/components/responses/415'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

  /registrations/{registrationId}:

    get:

      summary: Get an Individual PAS Registration

      operationId: GetIndPASReg

      tags:

        - Individual PAS Registration (Document)

      description: Retrieve an Individual PAS registration resource.

      parameters:

        - name: registrationId

          in: path

          description: Registration Id.

          required: true

          schema:

            type: string

      responses:

        '200':

          description: OK (The PAS registration information at the PIN Server).

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/PASRegistration'

        '307':

          $ref: 'TS29122_CommonData.yaml#/components/responses/307'

        '308':

          $ref: 'TS29122_CommonData.yaml#/components/responses/308'

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '406':

          $ref: 'TS29122_CommonData.yaml#/components/responses/406'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    put:

      summary: Update an Individual PAS Registration

      operationId: UpdateIndPASReg

      tags:

        - Individual PAS Registration (Document)

      description: Fully replace an existing PAS Registration resource.

      parameters:

        - name: registrationId

          in: path

          description: PAS Registration Id.

          required: true

          schema:

            type: string

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/PASRegistration'

      responses:

        '200':

          description: OK (The PAS registration information is updated successfully).

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/PASRegistration'

        '307':

          $ref: 'TS29122_CommonData.yaml#/components/responses/307'

        '308':

          $ref: 'TS29122_CommonData.yaml#/components/responses/308'

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '411':

          $ref: 'TS29122_CommonData.yaml#/components/responses/411'

        '413':

          $ref: 'TS29122_CommonData.yaml#/components/responses/413'

        '415':

          $ref: 'TS29122_CommonData.yaml#/components/responses/415'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    patch:

      summary: Modify an Individual PAS Registration

      operationId: ModifyIndPASReg

      tags:

        - Individual PAS Registration (Document)

      description: Partially update an existing PAS Registration resource.

      parameters:

        - name: registrationId

          in: path

          description: PAS registration Id.

          required: true

          schema:

            type: string

      requestBody:

        description: Partial update an existing PAS registration resource.

        required: true

        content:

          application/merge-patch+json:

            schema:

              $ref: '#/components/schemas/PASRegistrationPatch'

      responses:

        '200':

          description: >

            The Individual PAS registration is successfully modified and

            the updated registration information is returned in the response.

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/PASRegistration'

        '307':

          $ref: 'TS29122_CommonData.yaml#/components/responses/307'

        '308':

          $ref: 'TS29122_CommonData.yaml#/components/responses/308'

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '411':

          $ref: 'TS29122_CommonData.yaml#/components/responses/411'

        '413':

          $ref: 'TS29122_CommonData.yaml#/components/responses/413'

        '415':

          $ref: 'TS29122_CommonData.yaml#/components/responses/415'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    delete:

      summary: Delete an Individual PAS Registration

      operationId: DeleteIndPASReg

      tags:

        - Individual PAS Registration (Document)

      description: Delete an existing PAS registration at PIN server.

      parameters:

        - name: registrationId

          in: path

          description: Registration Id.

          required: true

          schema:

            type: string

      responses:

        '204':

          description: The individual PAS registration is deleted.

        '307':

          $ref: 'TS29122_CommonData.yaml#/components/responses/307'

        '308':

          $ref: 'TS29122_CommonData.yaml#/components/responses/308'

        '400':

          $ref: 'TS29122_CommonData.yaml#/components/responses/400'

        '401':

          $ref: 'TS29122_CommonData.yaml#/components/responses/401'

        '403':

          $ref: 'TS29122_CommonData.yaml#/components/responses/403'

        '404':

          $ref: 'TS29122_CommonData.yaml#/components/responses/404'

        '429':

          $ref: 'TS29122_CommonData.yaml#/components/responses/429'

        '500':

          $ref: 'TS29122_CommonData.yaml#/components/responses/500'

        '503':

          $ref: 'TS29122_CommonData.yaml#/components/responses/503'

        default:

          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

components:

  securitySchemes:

    oAuth2ClientCredentials:

      type: oauth2

      flows:

        clientCredentials:

          tokenUrl: '{tokenUrl}'

          scopes: {}

  schemas:

    PASRegistration:

      type: object

      description: Represents an PAS registration information.

      properties:

        conInfo:

          $ref: '#/components/schemas/ConnectivityInfo'

        expTime:

          $ref: 'TS29122_CommonData.yaml#/components/schemas/DateTime'

        requestorId:

          type: string

          description: Indentify a PAS

        passId:

          type: string

          description: Indentify a PIN service

      required:

        - requestorId

        - conInfo

        - passId

    ConnectivityInfo:

      type: object

      description: Represents a connection information of PAS.

      properties:

        fqdn:

          $ref: 'TS29571_CommonData.yaml#/components/schemas/Fqdn'

        ipv4Addrs:

          $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv4Addr'

        ipv6Addrs:

          $ref: 'TS29122_CommonData.yaml#/components/schemas/Ipv6Addr'

        uri:

          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'

      oneOf:

        - required: [uri]

        - required: [fqdn]

        - required: [ipv4Addrs]

        - required: [ipv6Addrs]

    PASRegistrationPatch:

      type: object

      description: Represents partial update request of individual PAS registration information.

      properties:

        conInfo:

          $ref: '#/components/schemas/ConnectivityInfo'

        expTime:

          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTimeRm'

        passId:

          type: string

          description: Identify a PIN service provided by PAS.