openapi: 3.0.0 info: title: API Definitions API description: >- Use the "API Definitions" API to manage your APIs by using the NGINX Controller API Management module. version: v1 servers: - description: NGINX Controller API url: 'https://{{CONTROLLER_FQDN}}/api/v1' paths: /services/api-definitions: get: tags: - API Definitions summary: List API Definitions description: Returns a list of API Definition resources. operationId: apiDefinitionsSearch responses: '200': description: Successfully retrieved a list of all API Definitions. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionList' '/services/api-definitions/{apiDefinitionName}': get: tags: - API Definitions summary: Get an API Definition description: | Gets information about a specified API Definition. operationId: apiDefinitionsGet responses: '200': description: >- Successfully returned the specified API Definition resource. content: application/json: schema: $ref: '#/components/schemas/APIDefinition' '404': description: The specified API Definition resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' put: tags: - API Definitions summary: Upsert an API Definition description: > Creates a new API Definition or updates an existing API Definition resource. operationId: apiDefinitionsPut requestBody: description: >- Defines the API Definition resource to create, or the updates to apply to an existing API Definition resource. content: application/json: schema: $ref: '#/components/schemas/APIDefinition' responses: '200': description: >- Successfully updated the specified API Definition resource. content: application/json: schema: $ref: '#/components/schemas/APIDefinition' '201': description: >- Successfully created the requested API Definition resource. content: application/json: schema: $ref: '#/components/schemas/APIDefinition' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' delete: tags: - API Definitions summary: Delete an API Definition description: Deletes the specified API Definition resource. operationId: apiDefinitionsDelete responses: '204': description: > Successfully deleted the requested API Definition resource. No content is returned. '404': description: The specified API Definition resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '409': description: > Failed to delete the specified API Definition resource. Delete any referenced Published APIs or remove the references, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' parameters: - $ref: '#/components/parameters/apiDefinitionName' '/services/api-definitions/{apiDefinitionName}/versions': get: tags: - API Definition Versions summary: List API Definition Versions description: > Lists all Versions for the specified API Definition resource. operationId: definitionVersionsSearch responses: '200': description: >- Successfully retrieved the list of API Definition Version resources. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersionList' '404': description: >- The specified API Definition resource was not found or does not contain any Versions. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' put: tags: - API Definition Versions summary: Add an API Definition Version description: > Creates a single new API Definition Version resource or multiple Version resources. operationId: definitionVersionsPutList requestBody: description: >- Creates, updates, or deletes an API Definition Version resource. It interacts with a list of items. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersionList' responses: '200': description: >- Successfully received the request to create the API Definition Version resource(s). content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersionList' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '409': description: >- Failed to delete the specified API Definition Version resource(s) as it has at least one dependent Published API. Delete the referenced Published API(s), then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' delete: tags: - API Definition Versions summary: Delete API Definition Versions description: > Deletes all Versions for the specified API Definition resource. operationId: definitionVersionsDeleteList responses: '204': description: > Successfully deleted the Versions for the requested API Definition resource. No content is returned. '404': description: >- The specified API Definition resource was not found or does not contain any Versions. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '409': description: > Failed to delete the Versions for the specified API Definition resource. Delete or remove any references to Published APIs, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' parameters: - $ref: '#/components/parameters/apiDefinitionName' '/services/api-definitions/{apiDefinitionName}/versions/{version}': get: tags: - API Definition Versions summary: Get an API Definition Version description: | Gets information about an API Definition Version resource. operationId: definitionVersionsGet responses: '200': description: >- Successfully returned the specified API Definition Version resource. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersion' '404': description: >- The specified API Definition Version resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' put: tags: - API Definition Versions summary: Upsert an API Definition Version description: > Creates a single new Version resource or updates an existing API Definition Version resource. operationId: definitionVersionsPut requestBody: description: Creates or updates an API Definition Version resource content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersion' responses: '200': description: >- Successfully updated the specified API Definition Version resource. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersion' '201': description: >- Successfully created the requested API Definition Version resource. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersion' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' delete: tags: - API Definition Versions summary: Delete an API Definition Version description: | Deletes an API Definition Version resource. operationId: definitionVersionsDelete responses: '204': description: > Successfully deleted the API Definition Version resource. '404': description: >- The specified API Definition Version resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '409': description: > Failed to delete the specified API Definition resource. Delete or remove any references to Published APIs, then try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' parameters: - $ref: '#/components/parameters/apiDefinitionName' - $ref: '#/components/parameters/versionName' '/services/api-definitions/{apiDefinitionName}/versions/{version}/import': put: tags: - API Definition Version Import summary: Import an API Definition Version description: > Imports an API spec to the specified Version of an API Definition. Use this endpoint to import a raw API specification to define your API. - This endpoint accepts a valid OpenAPI 3 spec, formatted as valid JSON or YAML. - The file provided for import will be validated against the [OAS v3 schema](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.yaml). - You must specify a "Content-Type" header when importing an API spec. The endpoint accepts the following "Content-Type" values: - application/json - application/yaml - text/x-yaml - application/x-yaml - text/yaml - application/xml - text/xml operationId: definitionVersionsImport requestBody: content: application/json: schema: type: object application/yaml: schema: type: string text/x-yaml: schema: type: string application/x-yaml: schema: type: string text/yaml: schema: type: string application/xml: schema: type: string text/xml: schema: type: string responses: '200': description: Successfully completed the API Version Import request. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersion' '201': description: >- Successfully created the requested API Definition Version resource from the spec provided. content: application/json: schema: $ref: '#/components/schemas/APIDefinitionVersion' '400': description: >- Bad input parameter, or possibly a bad URI. Check the input for typos and try again. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' '415': description: The request body contains an unsupported content type. content: application/json: schema: $ref: '#/components/schemas/ErrorModel' parameters: - $ref: '#/components/parameters/apiDefinitionName' - $ref: '#/components/parameters/versionName' components: schemas: APIDefinition: type: object properties: metadata: $ref: '#/components/schemas/ResourceMeta' currentStatus: $ref: '#/components/schemas/APIDefinitionCurrentStatus' APIDefinitionCurrentStatus: type: object properties: apiDefinitionVersionRefs: type: array items: $ref: '#/components/schemas/ResourceRef' APIDefinitionList: type: object properties: items: type: array items: $ref: '#/components/schemas/APIDefinition' APIDefinitionSpecMapping: type: object additionalProperties: anyOf: - $ref: '#/components/schemas/RESTAPISpec' - $ref: '#/components/schemas/gRPCProxySpec' - $ref: '#/components/schemas/SOAPAPISpec' RESTAPISpec: type: object description: > Validates an Imported OpenAPI 3 spec formatted as JSON using the [OAS v3 schema.yaml](https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v3.0/schema.yaml) specification. SOAPAPISpec: type: object description: | Validates and Transforms an Imported WSDL spec. properties: wsdl: type: string soap-config: $ref: '#/components/schemas/SoapConfig' required: - soap-config SoapConfig: type: object description: | Transformed WSDL to OpenAPI spec config. properties: name: type: string url: type: string tns: type: string qualifiedFields: type: boolean endpoints: type: object additionalProperties: $ref: '#/components/schemas/SoapConfigEndpoint' types: type: object additionalProperties: $ref: '#/components/schemas/SoapConfigWSDLType' messages: type: object additionalProperties: $ref: '#/components/schemas/SoapConfigMessage' required: - name - url - tns - endpoints - types - messages - qualifiedFields SoapConfigEndpoint: type: object properties: name: type: string in: type: string out: type: string enabled: type: boolean restHTTPMethod: type: string enum: - get - head - post - put - patch - delete restURI: type: string required: - name - in - out - enabled - restHTTPMethod - restURI SoapConfigMessage: type: object description: | Validates and Transforms an Imported WSDL spec. properties: name: type: string parts: type: object additionalProperties: $ref: '#/components/schemas/SoapConfigMessagePart' required: - name - parts SoapConfigMessagePart: type: object properties: name: type: string restName: type: string type: type: string ref: type: string required: - name - restName SoapConfigWSDLType: type: object properties: name: type: string type: type: string properties: type: array items: $ref: '#/components/schemas/SoapConfigNestedWSDLType' hasOneOfProperties: type: boolean hasOrderedProperties: type: boolean enum: type: array items: type: string required: - name - type - hasOneOfProperties - hasOrderedProperties SoapConfigNestedWSDLType: type: object properties: name: type: string restName: type: string type: type: string ref: type: string isRequired: type: boolean isArray: type: boolean required: - name - restName - isRequired - isArray gRPCProxySpec: x-f5-experimental: true type: object description: | Validates an Imported gRPC spec. APIDefinitionVersion: type: object properties: metadata: $ref: '#/components/schemas/APIDefinitionVersionMeta' desiredState: $ref: '#/components/schemas/APIDefinitionVersionDesiredState' currentStatus: $ref: '#/components/schemas/APIDefinitionVersionCurrentStatus' APIDefinitionVersionList: type: object properties: items: type: array items: $ref: '#/components/schemas/APIDefinitionVersion' APIDefinitionVersionDesiredState: type: object properties: specs: $ref: '#/components/schemas/APIDefinitionSpecMapping' APIDefinitionVersionCurrentStatus: type: object properties: specs: $ref: '#/components/schemas/APIDefinitionSpecMapping' state: $ref: '#/components/schemas/ConfigState' publishedApiRefs: type: array items: $ref: '#/components/schemas/ResourceRef' apiDefinitionVersionRef: type: object properties: ref: type: string description: | Reference to the Version of the API Definition. example: /services/api-definitions/baseball-stats/versions/v1 links: $ref: '#/components/schemas/NamedLinks' APIDefinitionVersionMeta: allOf: - $ref: '#/components/schemas/ResourceMeta' - type: object properties: isDefaultVersion: type: boolean SelfLinks: type: object description: > The SelfLinks object contains a link from the resource to itself. This object is used only in responses. properties: rel: type: string example: /api/v1/services/environments/prod description: > `rel` contains the complete path fragment of a URI and can be used to construct a query to the object. ResourceMeta: type: object required: - name properties: name: type: string pattern: >- ^[^A-Z\s\x00-\x1f\x60\x7f\;\*\"\[\]\{\}\\\/%\?:=&\~\^|#<>]+$ minLength: 1 maxLength: 1024 example: resource-name description: > Resource name is a unique identifier for a resource within the context of a namespace. Resource names must conform to [RFC 1738 Section 2.2](https://www.ietf.org/rfc/rfc1738.txt) and have a valid syntax for email addresses. The following rules are enforced: - do not utilize URL encoding; - do not include spaces; - do not use uppercase characters, for example, 'A-Z'; extended character sets are supported; - do not use the following characters: `"`, `*`, `:`, `;`, `/`, `\`, `%`, `?`, `hash`, `=`, `&`, `|`, `~`, `^`, `{`, `}`, `[`, `]`, `<`, `>`; - cannot start or end with an `@` sign; For example: For a collection resource located at `https://controller.example.com/api/v1/services/apps/shopping_@1` the resource name is "shopping_@1". displayName: type: string example: My Display Name description: > `displayName` is a user friendly resource name. It can be used to define a longer, and less constrained, name for a resource. Display names: - are optional (defaults to an empty string if no value is provided), - do not have to be unique, - cannot be assigned by the server. description: type: string example: >- This is a sample description string. It provides information about the resource. description: > `description` is a free-form text property. You can use it to provide information that helps to identify the resource. Descriptions: - are optional (defaults to an empty string if no value is provided), - do not have to be unique, - cannot be assigned by the server. kind: type: string example: - description: > Kind is a string representation of an API resource's data type. It is assigned by the server and cannot be changed. When creating a `kind`, the server uses hyphens to connect word segments; singleton and collection item resources are not pluralized. uid: type: string format: uuid example: d290f1ee-6c54-4b01-90e6-d701748f0851 description: > Unique Identifier (UID) UID is a unique identifier in time and space for a resource. When you create a resource, the server assigns a UID to the resource. Refer to [IETF RFC 4122](https://tools.ietf.org/html/rfc4122) for more information. tags: type: array items: type: string example: - production_public - dev - new_app - us-west-1 - emea description: > You can assign `tags` to a resource as a way to help map, scope, and organize resources. The system uses tag selectors to specify selection criteria that match resources that have particular tags. ref: type: string example: /services/environments/prod description: > The `ref` field contains a reference to another NGINX Controller resource. links: $ref: '#/components/schemas/SelfLinks' createTime: type: string format: date-time example: '2019-07-29T09:12:33.001Z' description: > A timestamp that represents the server time when the resource was created. Create time is not guaranteed to be set in "happens-before" order across separate operations. In JSON format, `create_time` type is encoded as a string in the [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). For example: 2018-04-01T01:30:15.01Z Create Time is assigned by the server and cannot be changed. updateTime: type: string format: date-time example: '2019-07-29T10:12:33.001Z' description: > A timestamp that represents the server time when the resource was last modified. Resources that have never been updated do not have an `update_time` stamp. The default value for resources that have never been updated is the local language-specific equivalent of "null". In JSON format, `update_time` type is encoded as a string as described in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). NamedLinks: allOf: - $ref: '#/components/schemas/SelfLinks' - type: object description: > Contains information about the object being referred to. These are generally details -- like the object name and display name -- that are useful to a consumer of the API that performs further processing. This object is only present in responses. properties: name: type: string example: production description: | The name of the linked resource. displayName: type: string example: Production Environment description: A user friendly resource name. ResourceRef: type: object required: - ref properties: ref: type: string example: /services/environments/prod description: | A reference to another NGINX Controller resource. links: $ref: '#/components/schemas/NamedLinks' ErrorDetail: type: object required: - description properties: description: type: string example: >- Error doing : . This can lead to . Try to resolve the issue. description: > A detailed error message returned by the server. These messages contain the following information, where applicable: - What happened. - Why it happened. - What the consequences are (if any). - Recommended action to take to resolve the issue. ErrorModel: type: object required: - message - code properties: message: type: string example: Error doing . description: > A human-readable message, in English, that describes the error. code: type: integer example: 1234567 description: > A numeric error code that can be used to identify errors for support purposes. details: type: array items: $ref: '#/components/schemas/ErrorDetail' ConfigStateTally: type: object properties: isConfigured: type: boolean description: The configuration operation is complete. isConfiguring: type: boolean description: >- The configuration of the resource, or of its child(ren), is in process. isError: type: boolean description: >- An error occurred while configuring the resource or its child(ren). isDeleting: type: boolean description: >- A delete operation is in progress for the resource or its child(ren). total: type: integer description: >- The total number of resources to which the configuration operation applies. configured: type: integer description: >- The number of resources that have a complete and valid configuration. configuring: type: integer description: >- The number of resources that are in the process of being configured. error: type: integer description: >- The number of resources that have encountered an error during the configuration process. deleting: type: integer description: >- The number of resources that are in the process of being deleted. ConfigCondition: type: object properties: type: type: string description: The condition type. message: type: string description: >- A human-readable message that provides additional information about the configuration operation. ConfigState: type: object description: > A representation of the resource's current configuration state that comprises the status of the resource itself (`selfConfigState`) and any child resources (`childrenConfigState`). The conditions array provides additional information during configuration changes. properties: selfConfigState: $ref: '#/components/schemas/ConfigStateTally' childrenConfigState: $ref: '#/components/schemas/ConfigStateTally' conditions: type: array items: $ref: '#/components/schemas/ConfigCondition' EnvironmentName: type: string AppName: type: string parameters: environmentName: name: environmentName description: >- The name of the Environment that contains the Component's parent App. in: path required: true schema: $ref: '#/components/schemas/EnvironmentName' appName: name: appName description: The name of the App that contains the Component resource. in: path required: true schema: $ref: '#/components/schemas/AppName' apiDefinitionName: name: apiDefinitionName in: path description: The name of the API Definition resource. required: true style: simple explode: false example: shopping-app-api-def schema: type: string publishedApiName: name: publishedApiName in: path description: The name of the Published API resource. required: true style: simple explode: false example: shopping-app-api-staging schema: type: string versionName: name: version in: path description: The Version of the API Definition. required: true style: simple explode: false example: v1_2fd4e1c6 schema: type: string