path: root/api-ref/source/parameters.yaml

####################
# Header Variables #
####################

x-auth-all-projects:
  description: |
    If enabled this will show results from all projects in Designate
  in: header
  required: false
  type: bool

x-auth-sudo-project-id:
  description: |
    This allows a user to impersonate another project
  in: header
  required: false
  type: string

x-auth-token:
  description: |
    Token used to identify the user from keystone
  in: header
  required: false
  type: string

x-designate-edit-managed-records:
  description: |
    If enabled this will all users to edit records flagged as managed
  in: header
  required: false
  type: bool

x-designate-hard-delete:
  description: |
    If enabled, this will delete the zone resources (i.e. files) on the
    back-end.
  in: header
  required: false
  type: bool

x-openstack-request-id:
  description: |
    ID of the request
  in: header
  required: true
  type: string

zone_export_accepts:
  description: >
    Content-Type that will be accepted by the client.
    This endpoint will send a response with a ``text/dns`` content-type.
    If the client does not include a ``Accepts: text/dns`` header
  in: header
  required: true
  type: string

####################
#  Path Variables  #
####################

blacklist_id:
  description: |
    ID for this blacklist
  in: path
  required: true
  type: uuid

floatingip_id:
  description: |
    ID for the floatingip associated with the project
  in: path
  required: true
  type: uuid

path_pool_id:
  description: |
    ID for this pool
  in: path
  required: true
  type: uuid

path_project_id:
  description: |
    ID for the project
  in: path
  required: true
  type: uuid

path_recordset_id:
  description: |
    ID for the recordset
  in: path
  required: true
  type: uuid

path_service_id:
  description: |
    ID for the service.
  in: path
  required: true
  type: uuid

path_zone_export_id:
  description: |
    ID for this zone export
  in: path
  required: true
  type: uuid

path_zone_id:
  description: |
    ID for the zone
  in: path
  required: true
  type: uuid

path_zone_import_id:
  description: |
    ID for this zone import
  in: path
  required: true
  type: uuid

path_zone_transfer_accept_id:
  description: |
    ID for this zone transfer accept
  in: path
  required: true
  type: uuid

path_zone_transfer_request_id:
  description: |
    ID for this zone transfer request
  in: path
  required: true
  type: uuid

region:
  description: |
    Openstack region
  in: path
  required: true
  type: string

tld_id:
  description: |
    ID for this tld
  in: path
  required: true
  type: uuid

tsigkey_id:
  description: |
    ID for this tsigkey
  in: path
  required: true
  type: uuid


####################
# Query Variables  #
####################

blacklist_pattern_filter:
  description: |
    Filter results to only show blacklists that have a pattern matching the filter
  in: query
  required: false
  type: string

limit:
  description: |
    Requests a page size of items. Returns a number
    of items up to a limit value. Use the ``limit`` parameter to make
    an initial limited request and use the ID of the last-seen item
    from the response as the ``marker`` parameter value in a
    subsequent limited request.
  in: query
  required: false
  type: integer

marker:
  description: |
    The ID of the last-seen item. Use the ``limit``
    parameter to make an initial limited request and use the ID of the
    last-seen item from the response as the ``marker`` parameter value
    in a subsequent limited request.
  in: query
  required: false
  type: string

recordset_data_filter:
  description: |
    Filter results to only show recordsets that have a record with data matching the filter
  in: query
  required: false
  type: string

recordset_description_filter:
  description: |
    Filter results to only show recordsets that have a description matching the filter
  in: query
  required: false
  type: string

recordset_name_filter:
  description: |
    Filter results to only show recordsets that have a name matching the filter
  in: query
  required: false
  type: string

recordset_status_filter:
  description: |
    Filter results to only show recordsets that have a status matching the filter
  in: query
  required: false
  type: string

recordset_ttl_filter:
  description: |
    Filter results to only show recordsets that have a ttl matching the filter
  in: query
  required: false
  type: string

recordset_type_filter:
  description: |
    Filter results to only show recordsets that have a type matching the filter
  in: query
  required: false
  type: string

sort_dir:
  description: |
    Sorts the response by the requested sort
    direction. A valid value is ``asc`` (ascending) or ``desc``
    (descending). Default is ``asc``. You can specify multiple pairs
    of sort key and sort direction query parameters. If you omit the
    sort direction in a pair, the API uses the natural sorting
    direction of the server attribute that is provided as the
    ``sort_key``.
  in: query
  required: false
  type: string

sort_key:
  description: |
    Sorts the response by the this attribute value.
    Default is ``id``. You can specify multiple pairs of sort key and
    sort direction query parameters. If you omit the sort direction in
    a pair, the API uses the natural sorting direction of the server
    attribute that is provided as the ``sort_key``.
  in: query
  required: false
  type: string

tld_name_filter:
  description: |
    Filter results to only show tlds that have a name matching the filter
  in: query
  required: false
  type: string

tsigkey_algorithm_filter:
  description: |
    Filter results to only show tsigkeys that have an algorithm matching the filter
  in: query
  required: false
  type: string

tsigkey_name_filter:
  description: |
    Filter results to only show tsigkeys that have a name matching the filter
  in: query
  required: false
  type: string

tsigkey_scope_filter:
  description: |
    Filter results to only show tsigkeys that have a scope matching the filter
  in: query
  required: false
  type: string

zone_description_filter:
  description: |
    Filter results to only show zones that have a description matching the filter
  in: query
  required: false
  type: string

zone_email_filter:
  description: |
    Filter results to only show zones that have an email matching the filter
  in: query
  required: false
  type: string

zone_export_message_filter:
  description: |
    Filter results to only show ``zone_exports`` that have a ``message`` matching the filter
  in: query
  required: false
  type: string

zone_export_status_filter:
  description: |
    Filter results to only show ``zone_exports`` that have a ``status`` matching the filter
  in: query
  required: false
  type: string

zone_export_zone_id_filter:
  description: |
    Filter results to only show ``zone_exports`` that have a ``zone_id`` matching the filter
  in: query
  required: false
  type: uuid

zone_import_message_filter:
  description: |
    Filter results to only show zone_imports that have a ``message`` matching the filter
  in: query
  required: false
  type: string

zone_import_status_filter:
  description: |
    Filter results to only show zone_imports that have a ``status`` matching the filter
  in: query
  required: false
  type: string

zone_import_zone_id_filter:
  description: |
    Filter results to only show zone_imports that have a ``zone_id`` matching the filter
  in: query
  required: false
  type: uuid

zone_name_filter:
  description: |
    Filter results to only show zones that have a name matching the filter
  in: query
  required: false
  type: string

zone_status_filter:
  description: |
    Filter results to only show zones that have a status matching the filter
  in: query
  required: false
  type: string

zone_transfer_accept_status_filter:
  description: |
    Filter results to only show ``zone_transfer_accepts`` that have a ``status`` matching the filter
  in: query
  required: false
  type: string

zone_transfer_request_status_filter:
  description: |
    Filter results to only show ``zone_transfer_requests`` that have a ``status`` matching the filter
  in: query
  required: false
  type: string

zone_ttl_filter:
  description: |
    Filter results to only show zones that have a ttl matching the filter
  in: query
  required: false
  type: integer

zone_type_filter:
  description: |
    Filter results to only show zones that have a type matching the filter
  in: query
  required: false
  type: string


####################
#  Body Variables  #
####################

action:
  description: |
    current action in progress on the resource
  in: body
  required: true
  type: enum

api_links:
  description: |
    Links to the resources in question.
  in: body
  required: true
  type: array

api_version_id:
  description: |
    A common name for the version.
  in: body
  required: true
  type: string

api_version_status:
  description: |
    The status of this API version. This can be one of:

    - ``CURRENT``: This is the preferred version of the API to use.
    - ``SUPPORTED``: This is an older, but still supported version of the API.
    - ``DEPRECATED``: A deprecated version of the API that is slated for
      removal.
    - ``EXPERIMENTAL``: This version is under development or contains features
      that are otherwise subject to change or removal.
  in: body
  required: true
  type: string

blacklist_description:
  description: |
    Description for this blacklist
  in: body
  required: false
  type: string

blacklist_pattern:
  description: |
    Pattern for this blacklist
  in: body
  required: true
  type: string

capabilities:
  description: |
    Capabilities for the service.
  in: body
  required: true
  type: dict

created_at:
  description: |
    Date / Time when resource was created.
  in: body
  required: true
  type: datestamp

description:
  description: |
    Description for the resource. Only shown in API / Horizon
  in: body
  required: true
  type: string

floatingip_address:
  description: |
    The floatingip address for this PTR record.
  in: body
  required: true
  type: string

fptr_description:
  description: |
    Description for this PTR record
  in: body
  required: true
  type: string

fptr_id:
  description: |
    ID for PTR record in the format of <region>:<floatingip_id>
  in: body
  required: true
  type: string

fptr_ttl:
  description: |
    Time to live for this PTR record
  in: body
  required: true
  type: uuid

fptrd_name:
  description: |
    Domain name for this PTR record
  in: body
  required: true
  type: string

heartbeated_at:
  description: |
    The timestamp when the last heartbeat was received.
  in: body
  required: true
  type: datestamp

hostname:
  description: |
    The hostname of the host with the service instance.
  in: body
  required: true
  type: string

id:
  description: |
    ID for the resource
  in: body
  required: true
  type: uuid

links:
  description: |
    Links to the resource, and other related resources.
    When a response has been broken into pages, we will include
    a ``next`` link that should be followed to retrieve all results
  in: body
  required: true
  type: object

max_page_limit:
  description: |
    The max amount of items allowed per page
  in: body
  required: true
  type: integer

max_recordset_name_length:
  description: |
    The max length of a recordset name
  in: body
  required: true
  type: integer

max_recordset_records:
  description: |
    The max amount of records contained in a recordset
  in: body
  required: true
  type: integer

max_zone_name_length:
  description: |
    The max length of a zone name
  in: body
  required: true
  type: integer

max_zone_records:
  description: |
    The max amount of records in a zone
  in: body
  required: true
  type: integer

max_zone_recordsets:
  description: |
    The max amount of recordsets per zone
  in: body
  required: true
  type: integer

max_zones:
  description: |
    The max amount of zones for this project
  in: body
  required: true
  type: integer

metadata:
  description: |
    Returns the ``total_count`` of resources matching this filter
  in: body
  required: true
  type: object

min_ttl:
  description: |
    The lowest ttl allowed on this system
  in: body
  required: true
  type: integer

pool_attributes:
  description: >
    Key:Value pairs of information about this pool. This information can be used by the scheduler to place zones on the correct pools
  in: body
  required: true
  type: object

pool_id:
  description: |
    ID for this pool
  in: body
  required: true
  type: uuid

pool_name:
  description: |
    Name for this pool
  in: body
  required: true
  type: string

pool_ns_records:
  description: |
    Name Servers for this pool. Any zones hosted by this pool should be delegated to these DNS servers
  in: body
  required: true
  type: string

project_id:
  description: |
    ID for the project that owns the resource
  in: body
  required: true
  type: uuid

recordset_description:
  description: |
    Description for this recordset
  in: body
  required: false
  type: string

recordset_name:
  description: |
    DNS Name for the recordset
  in: body
  required: true
  type: hostname

recordset_records:
  description: |
    A list of data for this recordset. Each item will be a separate record in Designate
    These items should conform to the DNS spec for the record type - e.g. A records
    must be IPv4 addresses, CNAME records must be a hostname.
  in: body
  required: true
  type: string

recordset_ttl:
  description: |
    TTL (Time to Live) for the recordset.
  in: body
  required: false
  type: integer

recordset_type:
  description: |
    They RRTYPE of the recordset.
  in: body
  required: true
  type: string

recordset_zone_id:
  description: |
    ID for the zone that contains this recordset
  in: body
  required: true
  type: uuid

recordset_zone_name:
  description: |
    The name of the zone that contains this recordset
  in: body
  required: true
  type: string

resource_id:
  description: |
    resource id for this tsigkey which can be either zone or pool id
  in: body
  required: true
  type: string

service_name:
  description: |
    The name of the Designate service instance.
  in: body
  required: true
  type: string

service_statuses:
  description: |
    A list of ``service_statuses`` objects.
  in: body
  required: true
  type: array

stats:
  description: |
    Statistics for the service.
  in: body
  required: true
  type: dict

status:
  description: |
    The status of the resource.
  in: body
  required: true
  type: enum

tld_description:
  description: |
    Description for this tld
  in: body
  required: false
  type: string

tld_name:
  description: |
    Name for this tld
  in: body
  required: true
  type: string

tsigkey_algorithm:
  description: |
    The encryption algorithm for this tsigkey
  in: body
  required: true
  type: string

tsigkey_name:
  description: |
    Name for this tsigkey
  in: body
  required: true
  type: string

tsigkey_scope:
  description: |
    scope for this tsigkey which can be either ZONE or POOL scope
  in: body
  required: true
  type: string

tsigkey_secret:
  description: |
    The actual key to be used
  in: body
  required: true
  type: string

updated_at:
  description: |
    Date / Time when resource last updated.
  in: body
  required: true
  type: datestamp

version:
  description: |
    Version of the resource
  in: body
  required: true
  type: integer

zone_attributes:
  description: |
    Key:Value pairs of information about this zone, and the pool the user
    would like to place the zone in. This information can be used by the
    scheduler to place zones on the correct pool.
  in: body
  required: false
  type: dict

zone_description:
  description: |
    Description for this zone
  in: body
  required: false
  type: string

zone_email:
  description: |
    e-mail for the zone. Used in SOA records for the zone
  in: body
  required: true
  type: string

zone_email_update:
  description: |
    e-mail for the zone. Used in SOA records for the zone
  in: body
  required: false
  type: string

zone_export_id:
  description: |
    ID for this zone export
  in: body
  required: true
  type: uuid

zone_export_location:
  description: >
    Where the exported zone is published to.
    There are currently one placement option available - designate.

    This will be shown by ``designate://<url>``.

    As more drivers are added, this will expand to include swift - this will be
    indicated by location being set to ``swift://<region>/<container>/<file>``

    This is also allowed be a webserver if the operator implements a different
    data store, and will be indicted by ``http://<url>``

    When a zone export is complete, the location will be updated, and
    the exported zone file will be available at the location specified.

  in: body
  required: false
  type: string

zone_export_message:
  description: |
    Message about the current status of the export
  in: body
  required: false
  type: uuid

zone_export_status:
  description: |
    Current status of the zone export
  in: body
  required: true
  type: string

zone_export_zone_id:
  description: |
    ID for the zone that is being exported
  in: body
  required: false
  type: uuid

zone_import_id:
  description: |
    ID for this zone import
  in: body
  required: true
  type: uuid

zone_import_message:
  description: |
    Message about the current status of the import
  in: body
  required: false
  type: uuid

zone_import_status:
  description: |
    Current status of the zone import
  in: body
  required: true
  type: uuid

zone_import_zone_id:
  description: |
    ID for the zone that was created by this import
  in: body
  required: false
  type: uuid

zone_masters:
  description: |
    Mandatory for secondary zones. The servers to slave from to get DNS information
  in: body
  required: false
  type: enum

zone_name:
  description: |
    DNS Name for the zone
  in: body
  required: true
  type: domainname

zone_nameserver_hostname:
  description: |
    The hostname of the nameserver that the zone should be delegated to
  in: body
  required: true
  type: hostname

zone_nameserver_priority:
  description: |
    The priority of the nameserver. This is used to determine the order of the
    the nameserver listings, and which server is used in the SOA record for the
    zone.
  in: body
  required: true
  type: integer

zone_pool_id:
  description: |
    ID for the pool hosting this zone
  in: body
  required: true
  type: uuid

zone_serial:
  description: |
    current serial number for the zone
  in: body
  required: true
  type: integer

zone_transfer_accept_id:
  description: |
    ID for this zone transfer accept
  in: body
  required: true
  type: uuid

zone_transfer_accept_status:
  description: |
    Current status of the zone transfer request
  in: body
  required: true
  type: string

zone_transfer_request_id:
  description: |
    ID for this zone transfer request
  in: body
  required: true
  type: uuid

zone_transfer_request_key:
  description: >
    Key that is used as part of the zone transfer accept process. This is only
    shown to the creator, and must be communicated out of band.
  in: body
  required: true
  type: string

zone_transfer_request_status:
  description: |
    Current status of the zone transfer request
  in: body
  required: true
  type: string

zone_transfer_request_target_project_id:
  description: >
    A project ID that the request will be limited to.
    No other project will be allowed to accept this request.
  in: body
  required: false
  type: string

zone_transfer_request_zone_id:
  description: |
    ID for the zone that is being exported
  in: body
  required: true
  type: uuid

zone_transfer_request_zone_name:
  description: |
    the name of the zone that is being exported
  in: body
  required: true
  type: string

zone_transfered_at:
  description: |
    For secondary zones. The last time an update was retrieved from the master servers
  in: body
  required: true
  type: enum

zone_ttl:
  description: |
    TTL (Time to Live) for the zone.
  in: body
  required: false
  type: integer

zone_type:
  description: |
    Type of zone. PRIMARY is controlled by Designate, SECONDARY zones are slaved from another DNS Server. Defaults to PRIMARY
  in: body
  required: false
  type: enum