openapi: 3.0.0
info:
  title: ANS API
  version: 0.0.1
servers:
  - url: https://example.com/api/validator
tags:
  - name: ans
paths:
  /v0/entry/create:
    post:
      summary: "POST /v0/entry/create"
      description: |
        Requests the creation of a new ANS entry.
        ANS entries need to be paid and renewed via subscription payments.

        Upon requesting the creation of the ANS entry, a subscription request is created.
        The user may accept the subscription request via their wallet by offering the initial payment.
        Once the subscription request is accepted, the DSO automation burns the payment and creates the ANS entry.
      tags:
        - ans
      x-jvm-package: external.ans
      operationId: createAnsEntry
      security:
        - userAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnsEntryRequest'
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAnsEntryResponse'
        '400':
          description: |
            Invalid request, check the error response for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/500'
  /v0/entry/all:
    get:
      summary: "GET /v0/entry/all"
      description: |
        Lists all ANS entries owned by the user.
        Expired entries are not included in the response, even if the corresponding contracts are still active on the ledger.
      tags:
        - ans
      x-jvm-package: external.ans
      operationId: listAnsEntries
      security:
        - userAuth: []
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAnsEntriesResponse'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
components:
  securitySchemes:
    userAuth:
      description: |
        JWT token as described by the `spliceAppBearerAuth` security scheme.
        The subject of the token must be ledger API user of the user affected by the endpoint.
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    CreateAnsEntryRequest:
      type: object
      required:
        - name
        - url
        - description
      properties:
        name:
          type: string
          description: |
            The name of the ANS entry.
            It must end with `.unverified.<ans>` where `<ans>` is the ANS acronym chosen by the DSO.
        url:
          type: string
          description: |
            A valid URL or an empty string.
            Use this to link to a website, such as the homepage of an application
            provided by the owner of this entry.
            Must not be longer than 255 characters.
        description:
          type: string
          description: |
            A human readable description of the ANS entry.
            May be empty.
            Must not be longer than 140 characters.
    CreateAnsEntryResponse:
      description: |
        The response contains the contract IDs of the corresponding subscription request.
        The user must accept the subscription request via their wallet to create the ANS entry.
      type: object
      required:
        - name
        - url
        - description
        - entryContextCid
        - subscriptionRequestCid
      properties:
        entryContextCid:
          $ref: '#/components/schemas/ContractId'
        subscriptionRequestCid:
          $ref: '#/components/schemas/ContractId'
        name:
          type: string
          description: |
            The name of the ANS entry, as specified in the request.
        url:
          type: string
          description: |
            The URL of the ANS entry, as specified in the request.
        description:
          type: string
          description: |
            The description of the ANS entry, as specified in the request.
    ListAnsEntriesResponse:
      type: object
      required:
        - entries
      properties:
        entries:
          type: array
          items:
            $ref: '#/components/schemas/AnsEntryResponse'
    AnsEntryResponse:
      type: object
      required:
        - contractId
        - name
        - amount
        - unit
        - expiresAt
        - paymentInterval
        - paymentDuration
      properties:
        contractId:
          $ref: '#/components/schemas/ContractId'
        name:
          type: string
        amount:
          type: string
        unit:
          type: string
        expiresAt:
          type: string
        paymentInterval:
          type: string
        paymentDuration:
          type: string
    ContractId:
      type: string
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
  responses:
    '404':
      description: not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'