DevOps Pipeline Task Name: FaUAPI-Configure-Api-Group

This FaUAPI DevOps pipeline task will configure a new API group based on the structure and metadate within a definitions file before the API group is created. It can be considered the most basic and default FaUAPI DevOps pipeline task that can be performed on an API group.

The required inputs for this pipeline task are outlined in the table below: | Input Name | Required? | Type | Description | Default Value | | --------------- | ------------------------------ | ----------------------------------------------------------------------------------- |------------------- |------------------ | | AutomationToken | Required | String | Workspace automation token. This is obtained by following the steps in Adding a workspace automation token. | - | FaUAPIInstance | Required | String | Instance which the API is to be configured. Valid value string are ('DEV', 'Test', 'PREPROD', 'PROD'). | - DefinitionFilePath | Required | String | Path to the definition file within the current repository. | - RemoveUndeclaredResources | Required | Boolean | Remove resources that are not specified in the JSON file. False - Ignore resources. | - |

Now, let's look at an example of configuring an API group using the FaUAPI DevOps pipeline tasks extension.

Example 1:

To configure an API group using FaUAPI DevOps pipeline task:

  1. Go to DfE Azure DevOps URL.
  2. Sign in to DfE Azure DevOps.
  3. Go to the Solutions Development project.
  4. Select Pipelines from the left sidebar tab options. This will show you the Pipeline page with search.
  5. Type the word or phrase for the pipeline task you want to create into the search box.
  6. Select the relevant FaUAPI DevOps pipeline task from the search result. This will show you the pipeline task creation page.
  7. Select the relevant environment from the FaUAPI instance radio options (Development, Test, Pre-Production, Production).

Development and Test instanes are for use by the FaUAPI development and support team only. 8. Enter your automation token into the Automation Token textbox. It is recommended as best practice to use the automation token variable $(AUTOMATION-TOKEN) stored within a variable group in pipeline library. So, assign the value of the automation token to this variable. You can generate an automation token by following the steps described in Adding a workspace automation token. 9. Enter the URL or path to the location of your API group definition file (JSON) into the API group definition file textbox. This definition file contains all the required information about the API group including fields, metadata, schema etc. And ensure it is within the same repository and folder as the pipeline file (Yaml format). 10. Select if resources not included in the JSON should be removed with the Remove undeclared resources option set to 'true'. 11. Select the Add button. This will save the details. 12. Select the Run button to run your pipeline.

When a pipeline is run, it validates the inputs, and where there is an error such as an incorrect key, or invalid input, it will fail and return the relevant error message to indicate the error. And when successful, it returns a list of task performed, ID number for the record created and details of resultant record.

Sample Pipeline YAML file (API only)

Here is an sample pipeline YAML file for configuring an API group only. The parameters and sensitive values such as the Automation token secret key (Primary and Secondary keys) are stored in a variable group within the pipeline library and not assigned as plain text values within the YAML or JSON files. Alternatively, there is the option to store such sensitive values wihin Azure DevOps key vault.

variables:
 - group: "EXAMPLE-VARIABLE-GROUP"
      
steps:
- task: FaUAPI-Configure-API-Group@1
  inputs:
    AutomationToken: "$(AUTOMATION-TOKEN)"
    FaUAPIInstance: "$(TARGET-INSTANCE)"
    ApiGroupDefinition: "json/apigroup.json"
- task: FaUAPI-Publish-API-Group@1
  inputs:
    AutomationToken: "$(AUTOMATION-TOKEN)"
    FaUAPIInstance: "$(TARGET-INSTANCE)"
    ApiName: "$(API_GROUP_NAME)"

Sample API group definition file (JSON)

{
  "backendType": "http",
  "classification": "Across government services",
  "description": "This is an example description of sufficient length.",
  "displayName": "Example API group",
  "isHosted": true,
  "majorVersion": "1",
  "name": "example-api",
  "overview": "This is an example overview. You need this in order to publish this API group.",
  "versionScheme": "UrlSuffix",
  "visibility": "Private",
  "schema": {
      "description": "This is an example API group schema.",
      "fileName": "schema.json",
      "name": "schema.json",
      "type": "schema",
      "schemaType": "openapi",
      "DefinitionFilePath": "json/schema.json"
  },
  "authentications":[
    {
      "autoEnforce": true,
      "enabled": true,
      "parameters": {
        "HeaderName": "Ocp-Apim-Subscription-Key",
        "QueryName": "Subscription-Key"
      },
      "type": "SubscriptionKey"
    }
  ],
  "environments": [
    {
      "backendMode": "Explicit",
      "backendUrl": "http://www.example.com/",
      "canSubscribe": true,
      "enabled": true,
      "name": "live",
      "requiresApproval": false,
      "visibility": "Inherit"
    }
  ],
  "releases": [
    {
      "availableFrom": "2025-09-01",
      "availableTo": "2025-12-30",
      "isCurrent": true,
      "name": "1.0",
      "notes": "Example release notes\r\nThis can contain *markdown*",
      "tag": "Live"
    }
  ]
}

Sample schema file (JSON)

{
    "openapi": "3.0.1",
    "info": {
      "title": "Api Group Example",
      "version": "v1"
    },
    "servers": [
      {
        "url": "https://example-api.platform.education.gov.uk/v1"
      }
    ],
    "paths": {
      "/api/linked-test": {
        "post": {
          "tags": [
            "example_post"
          ],
          "summary": "Run",
          "operationId": "Run",
          "responses": {
            "200": {
              "description": "Success"
            }
          }
        }
      },
      "/api/example-get": {
        "get": {
          "tags": [
            "example_get"
          ],
          "summary": "Dog",
          "operationId": "Dog",
          "responses": {
            "200": {
              "description": "Success"
            }
          }
        }
      }
    },
    "components": {
      "securitySchemes": {
        "apiKeyHeader": {
          "type": "apiKey",
          "name": "Ocp-Apim-Subscription-Key",
          "in": "header"
        },
        "apiKeyQuery": {
          "type": "apiKey",
          "name": "subscription-key",
          "in": "query"
        }
      }
    },
    "security": [
      {
        "apiKeyHeader": [ ]
      },
      {
        "apiKeyQuery": [ ]
      }
    ]
  }

Sample FaUAPI DevOps Pipeline task success message

Sample FaUAPI DevOps Pipeline task error message

Example 2:

Configuring an API group with documents using DevOps pipeline task

Sample Pipeline YAML file

In the sample pipeline file, you

variables:
 - group: "EXAMPLE-VARIABLE-GROUP"
      
steps:
- task: FaUAPI-Configure-API-Group@1
  inputs:
    AutomationToken: "$(AUTOMATION-TOKEN)"
    FaUAPIInstance: "$(TARGET-INSTANCE)"
    ApiDefinition: "json/api.json"
- task: FaUAPI-Publish-API@1
  inputs:
    AutomationToken: "$(AUTOMATION-TOKEN)"
    FaUAPIInstance: "$(TARGET-INSTANCE)"
    ApiName: "$(API_NAME)"

Sample API definition file (JSON)

{
  "backendType": "http",
  "classification": "Across government services",
  "description": "This is an example description of sufficient length",
  "displayName": "Example API group",
  "isHosted": true,
  "majorVersion": "1",
  "name": "example-api",
  "overview": "This is an example overview. You need this in order to publish.",
  "versionScheme": "UrlSuffix",
  "visibility": "Private",
  "schema": {
      "description": "This is an example API group schema",
      "fileName": "schema.json",
      "name": "schema.json",
      "type": "schema",
      "schemaType": "openapi",
      "DefinitionFilePath": "json/schema.json"
  },
  "authentications":[
    {
      "autoEnforce": true,
      "enabled": true,
      "parameters": {
        "HeaderName": "Ocp-Apim-Subscription-Key",
        "QueryName": "Subscription-Key"
      },
      "type": "SubscriptionKey"
    }
  ],
  "environments": [
    {
      "backendMode": "Explicit",
      "backendUrl": "http://www.example.com/",
      "canSubscribe": true,
      "enabled": true,
      "name": "live",
      "requiresApproval": false,
      "visibility": "Inherit"
    }
  ],
  "releases": [
    {
      "availableFrom": "2025-09-01",
      "availableTo": "2025-12-30",
      "isCurrent": true,
      "name": "1.0",
      "notes": "Example release notes\r\nThis can contain *markdown*",
      "tag": "Live"
    }
  ]
}

Sample Openapi schema file (JSON)

{
    "openapi": "3.0.1",
    "info": {
      "title": "Api group Example",
      "version": "v1"
    },
    "servers": [
      {
        "url": "https://example-api.platform.education.gov.uk/v1"
      }
    ],
    "paths": {
      "/api/linked-test": {
        "post": {
          "tags": [
            "example_post"
          ],
          "summary": "Run",
          "operationId": "Run",
          "responses": {
            "200": {
              "description": "Success"
            }
          }
        }
      },
      "/api/example-get": {
        "get": {
          "tags": [
            "example_get"
          ],
          "summary": "Dog",
          "operationId": "Dog",
          "responses": {
            "200": {
              "description": "Success"
            }
          }
        }
      }
    },
    "components": {
      "securitySchemes": {
        "apiKeyHeader": {
          "type": "apiKey",
          "name": "Ocp-Apim-Subscription-Key",
          "in": "header"
        },
        "apiKeyQuery": {
          "type": "apiKey",
          "name": "subscription-key",
          "in": "query"
        }
      }
    },
    "security": [
      {
        "apiKeyHeader": [ ]
      },
      {
        "apiKeyQuery": [ ]
      }
    ]
  }