openapi: 3.0.0
info:
  title: BuddyNS.com API
  description: API to [BuddyNS](https://www.buddyns.com), a DNS replication service.
    This API allows you to control the zones (domain names) you replicate,
    as well as your account and service parameters. Build powerful, well-integrated
    plug-ins or automation with BuddyNS.
    The API is sits at the highest maturity level in
    [Richardson's REST Maturity Model](https://restfulapi.net/richardson-maturity-model/).
  version: 2.0.2
servers:
  - url: https://www.buddyns.com/api/v2/
tags:
  - name: zone
    description: Control zones and their status.
  - name: user
    description: Control user account and profile.
  - name: service
    description: Monitor parameters of the service provisioned with the account.
  - name: sync
    description: Control of near-immediate synchronization of DNS zone data.
paths:
  /zone/:
    get:
      tags:
        - zone
      summary: Returns a list of zones.
      description: The list includes properties of each zone.
      responses:
        '200':
          description: Array of Zone objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Zone'
        '401':
          $ref: "#/components/responses/UnauthorizedError"          
        '429':
          description: Request throttled.
    post:
      tags:
        - zone
      summary: Adds a zone.
      description: Creates a new zone in the account, provided that no parent of the zone is registered under another account.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Zone'
          application/json:
            schema:
              $ref: '#/components/schemas/Zone'
      responses:
        '201':
          description: Zone created.
        '400':
          description: Invalid zone data submitted (exist already, or parent does, or invalid parameters).
        '401':
          $ref: "#/components/responses/UnauthorizedError"

  /zone/{zname}:
    get:
      tags:
        - zone
      summary: Get details about a zone.
      description: Returns configuration and status details about a zone as currently stored on BuddyNS.
      parameters:
        - in: path
          name: zname
          description: Name (and unique identifier) of the zone to get details for.
          required: true
          schema:
            type: string
            format: hostname
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Zone'
    delete:
      tags:
        - zone
      summary: Remove zone.
      description: Removes zone from BuddyNS account.
      parameters:
        - in: path
          name: zname
          description: Name (and unique identifier) of the zone to get details for.
          required: true
          schema:
            type: string
            format: hostname
      responses:
        '204':
          description: OK
        '400':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultDetail'
        '401':
          $ref: "#/components/responses/UnauthorizedError"
        '404':
          description: Not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultDetail'
  /zone/{zname}/status/:
    get:
      tags:
        - zone
      summary: Get details about a zone's status.
      description: Returns the status of the zone data and transfer, including timestamp.
      parameters:
        - in: path
          name: zname
          description: Name (and unique identifier) of the zone to get details for.
          required: true
          schema:
            type: string
            format: hostname
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneStatus'
        '401':
          $ref: "#/components/responses/UnauthorizedError"

  /zone/{zname}/delegation/:
    get:
      tags:
        - zone
      summary: Get details about a zone's DNS delegation status.
      description: Returns configuration and status details about a zone as currently stored on BuddyNS.
      parameters:
        - in: path
          name: zname
          description: Name (and unique identifier) of the zone to get details for.
          required: true
          schema:
            type: string
            format: hostname
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoneDelegation'
        '401':
          $ref: "#/components/responses/UnauthorizedError"

  # user
  /user/:
    get:
      tags:
        - user
      summary: Get essential user parameters.
      responses:
        '200':
          description: User details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: "#/components/responses/UnauthorizedError"

  /user/profile/:
    get:
      tags:
        - user
      summary: Get details on profile and usage.
      responses:
        '200':
          description: User profile details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: "#/components/responses/UnauthorizedError"
    put:
      tags:
        - user
      summary: Update details on user profile.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UserProfile'
          application/json:
            schema:
              $ref: '#/components/schemas/UserProfile'
      responses:
        '200':
          description: OK, operation performed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultDetail'
        '400':
          description: Invalid parameter format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultDetail'
        '401':
          $ref: "#/components/responses/UnauthorizedError"

  /service/:
    get:
      tags:
        - service
      summary: Get parameters on the service level and restrictions.
      description: Available limits for each account type is described in detail on https://www.buddyns.com/services/#plans-comparison .
      responses:
        '200':
          description: OK, data returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          $ref: "#/components/responses/UnauthorizedError"

  /sync/:
    get:
      tags:
        - sync
      summary: Perform zone transfer (SyncNOW) on all zones in the account.
      responses:
        '204':
          description: OK, operation performed.
        '401':
          $ref: "#/components/responses/UnauthorizedError"

  /sync/{zname}:
    get:
      tags:
        - sync
      summary: Perform zone transfer (SyncNOW) on a given zone.
      parameters:
        - in: path
          name: zname
          description: Name (and unique identifier) of the zone to get details for.
          required: true
          schema:
            type: string
            format: hostname
          
      responses:
        '204':
          description: OK, operation performed.
        '401':
          $ref: "#/components/responses/UnauthorizedError"
        '404':
          description: Zone not found, or operation not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultDetail'

components:
  schemas:
    Zone:
      type: object
      properties:
        name:
          type: string
          description: Domain of the zone, a valid host name as defined in RFC1123, Section 2.
          format: hostname
        name_idn:
          type: string
          readOnly: true
          format: hostname
        creation_ts:
          type: string
          readOnly: true
          description: Timestamp of creation of zone into BuddyNS.
          format: date-time
        master:
          type: string
          description: IP address of master (primary) server, from which BuddyNS will AXFR from; IPv4 and IPv6 are allowed. Addresses in reserved ranges like 127.0.0.0/8 and 172.16.0.0/12 are rejected.
          format: ipv4
        serial:
          type: number
          readOnly: true
          minimum: 0
          maximum: 4294967295
          example: 2019070901
          description: Latest serial number acquired by BuddyNS for zone.
        status:
          type: string
          readOnly: true
          format: uri
          description: URL to status detail for this zone.
        delegation:
          type: string
          readOnly: true
          format: uri
          description: URL to delegation status detail for this zone.
      required:
        - name
        - master
      example:
        name: bücher.de
        name_idn: xn--bcher-kva.de
        master: 65.55.37.62
        serial: 2019070904
    ZoneStatus:
      type: object
      properties:
        zone:
          type: string
          format: hostname
          readOnly: true
          example: bücher.com
        transfer_ok:
          type: boolean
        first_failure_ts:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        last_failure_ts:
          type: string
          format: date-time
          readOnly: true
          nullable: true
        last_success_ts:
          type: string
          format: date-time
          readOnly: true
          nullable: true
    ZoneDelegation:
      type: object
      properties:
        zone:
          type: string
          format: hostname
          example: sun.com
        master:
          type: string
          format: ipv4
        master_ok:
          type: boolean
        registry_ok:
          type: boolean
        authority_ok:
          type: boolean
    User:
      type: object
      properties:
        email:
          type: string
          format: email
      required:
        - email
    UserProfile:
      type: object
      properties:
        used_traffic:
          type: integer
          readOnly: true
          description: Number of queries performed for zones under this account.
          minimum: 0
          example: 10
        estimated_traffic:
          type: integer
          readOnly: true
          description: Estimated number of queries that will per performed per month, based on latest traffic rate.
          minimum: 0
          example: 1234
        mobile_number:
          type: string
          description: Mobile phone number in ITU-T E.123 format.
          pattern: '^\+\d{1,16}'
          example: "+19876789123"
        cpanel_integration:
          type: boolean
          description: Whether cPanel integration is enabled for this account.
      required:
        - used_traffic
        - estimated_traffic
        - mobile_number
        - cpanel_integration
    Service:
      type: object
      properties:
        account_type:
          type: string
          enum: [free, advanced, astronaut, enterprise]
          description: Name of account type.
        num_zones:
          type: integer
          readOnly: true
          nullable: true
          minimum: 0
          description: Maximum number of zones allowed in account; null means unbounded.
        traffic_quota:
          type: integer
          readOnly: true
          minimum: 0
          description: Maximum collective amount of DNS queries allowed per month for zones in account, in thousands.
        num_stats:
          type: integer
          readOnly: true
          minimum: 0
          nullable: true
          description: Maximum number of zones available for GeoStats tracking; null means unbounded.
      example:
        account_type: free
        num_zones: null
        traffic_quota: 3000
        num_stats: 10
    ResultDetail:
      type: object
      properties:
        detail:
          type: string
          description: Error description.
          readOnly: true
          example: Not found.

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

  responses:
    UnauthorizedError:
      description: Authentication token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResultDetail'
            
security:
  - ApiKeyAuth: []
    
externalDocs:
  description: "Why you need DNS redundancy."
  url: "https://www.buddyns.com/services/"