In this section, you will be guided through the process of managing Linked APIs which are hosted within the DfE service and is one the two types of APIs you can add to your workspace within the DfE part of the DfE Find and Use an API Management Portal.

Adding a Linked API to a workspace

To add a Linked API to your workspace:

  1. Select the Add an API link from the API section of the Overview page. This will show you the **Add API ** page.
  2. Select the Linked option for the type of API.
  3. Select the Continue button to proceed. Or Return to workspace overview link to cancel.
  4. Enter a friendly name for the API into the API name text box. This will help you identify this API from others you may add.
  5. Enter a description into the Description text box.
  6. Select the API Backend type from the dropdown option (currently HTTP only).
  7. Enter the Major version identifier.
  8. Select the Save API button to add your API. Or the Return to workspace overview link to cancel. This will show you to the API details page for the newly added API with menu options including:
  • Overview
  • Metadata
  • Documents
  • Releases
  • Environments
  • Operations

Overview

The overview page for your Linked API will contain details of the workspace including:

  • API type (Linked)
  • Backend type (HTTP, SOAP or GraphQL)
  • Visibility (Private, DfE Internal or Public) See API visibility levels
  • Schema (including a Change link to replace any existing schemas) - Optional. This allows you to upload an OpenAPI or Swagger schema for the API. The schema generates all the operations and allow users within the DfE's Find and Use API Consumption Portal can see what your API does.
  • Status (Published or Draft). See API publication statuses
  • Published version (including a Publish link to publish your API)
  • Subscription count (This would have no value as Linked APIs cannot be subscribed to from the DfE's Find and Use API Consumption Portal)

By default, all APIs added to a workspace and published to the DfE API catalogue have their visibility set as Private, so you will need to change this to Public if you want your API visible to all users.

Changing the Visibility of a workspace Linked API

To change the Visibility of your Linked API:

  1. Select the Change link next to the visibility setting within the API's detail page overview option. This will show you the Change API visibility page.
  2. Select the API visibility radio option you wish to use (Private, DFE Internal, Public).
  3. Select Save changes to update the visibility. Or the Return to API overview link to cancel.

You can read about API visibility levels at anytime by selecting the Click here for guidance on API visibility levels link.

Changing the schema for a workspace Linked API

To change the schema for your Linked API:

  1. Select the Change link next to the schema detail within API's detail page overview option. This will show you the Change API schema upload page where you can also view the content of the schema file.
  2. Select the schema type option for the file you wish to upload (OpenAPI or Swagger in JSON or XML format). This is optional.
  3. Select the button to Choose file under the schema file section to browse to the location of file to upload.
  4. Select Upload schema button to upload the selected schema file. Or Return to API overview link to cancel. Uploading a schema file will show you a refreshed Change API schema page with these sections:
  • Schema changes showing details of what will be added or deleted from operations policy including the operation name, description and method.
  • Verify schema import details including Schema type, Schema file
  • Operations section with details including the method, description, URL template for the API.
  1. Select Apply schema button to verify and update the schema. Or the Return to API overview link to cancel.

Uploading a new schema for an API will overwrite any existing API operations.

Viewing the schema file for a workspace Linked API

To view the schema file for your Linked API:

  1. Select the Change link next to the schema detail within the API's Overview page option. This will take you to the Change API schema upload page where you can also view the content of the schema file.

Preview changes of a schema upload to a workspace Linked API

To preview changes and impact on an API operation scope policy due to a new schema file upload for your Linked API:

  1. Select the Change link next to the schema detail within API's detail page overview option. This will show you the Change API schema upload page where you can also view the content of the schema file.
  2. Select the schema type option for the file you wish to upload (OpenAPI or Swagger in JSON or XML format). This is optional.
  3. Select the button to Choose file under the schema file section to browse to the location of file to upload.
  4. Select Upload schema button to upload the selected schema file. Or Return to API overview link to cancel. Uploading a schema file will show you a refreshed Change API schema page with these sections:
  • Schema changes - showing details of what will be added or deleted from the operations policy including operation name, description and method.
  • Verify schema import - showing details including schema type and schema file
  • Operations section - showing details including the method, description and URL template for the API.
  1. Select Apply schema button to verify and update the schema with the changes highlighted. Or the Return to API overview link to cancel.
  2. Repeat Step 1 to Step 5 again to upload a new schema. This will refresh the Change API schema page with details of what will be added or deleted from API operations policy before you choose to apply the schema change.
  3. Select the Apply schema button to update the schema. Or the Return to API overview link to cancel.

Downloading the schema for a workspace Linked API

To Download the schema for your Linked API:

  1. Select the Download link next to the schema detail within the API's Overview page. This will automatically download the schema file into your browser assigned Download folder.

Metadata

The metadata page provides descriptive information about the data and actions of the API that can be used to optimise searches including:

  • Name - The name given to the API.
  • Description - A short description and summary about the API.
  • Tags - Related keywords words or phrase that help to optimise searches for the API. Each tag must be separated by a semicolon.
  • Data exposure classification (Mandatory) - See data exposure classification

The Project Information section within this page contains details including:

  • Project URL - A resource location to the project's website or git repository.
  • CDDO API Id - Unique identifier assigned to an API by the Central Digital and Data Office (CDDO) for reporting purposes. These are assigned to APIs registered with the CDDO only.

And the Further Information section includes the following:

  • Overview - A summary of the API and project.
  • Who can use - Description of who can use the API and benefits.
  • Service level - Defines the level of quality, performance, and availability of the API.
  • Technologies - Information ontechnologies used, supported or integrated products.

And finally, a Save changes button to update the API metadata or Return to API metadata link to cancel.

Adding metadata to a workspace Linked API

To add metadata to your Linked API:

  1. Select Metadata from the left side menus tab. This will show you the API metadata page with details including description, data exposure classification.
  2. Select the Edit metadata link. This will show you the Edit API metadata page with 3 sections:
  • Searchable data (including Description, Tags, Data exposure classification)
  • Project information (including Project URL, CDDO API Id)
  • Further information (including Overview, Who can use, Service level, Technologies)
  1. Enter the following metadata information for your API in the different sections:

  • Searchable data

    • Description - Enter this into the Description text box
    • Tags - Enter this into the Tags text box with each tag separated by a semicolon
    • Data exposure classification - Select from options provided in dropdown list See data exposure classification

  • Project information

    • Project URL - Enter this into the Project URL text box
    • CDDO API Id - Enter this into the CDDO API Id text box

  • Further information

    • Overview - Enter this into the Overview text box
    • Who can use - Enter this into the Who can use text box
    • Service level
    • Technologies
  1. Select the Save changes button. Or the Return to API metadata.

Editing metadata for a workspace Linked API

To edit metadata for your Linked API:

  1. Select Metadata from the left side menus tab. This will show you the API metadata page with details including description, data exposure classification.
  2. Select the Edit metadata link. This will show you the Edit API metadata page with 3 sections:
  • Searchable data (including Name, Description, Tags, Data exposure classification)
  • Project information (including Project URL, CDDO API Id)
  • Further information (including Overview, Who can use, Service level, Technologies)
  1. Enter the update within the relevant metadata information for your API in the relevant section:

  • Searchable data

    • Name - Enter any new API name into the Name text box
    • Description - Enter any new the description into the Description text box
    • Tags - Enter the tag update into the Tags text box with each tag separated by a semicolon
    • Data exposure classification - Select from options provided in dropdown list See data exposure classification

  • Project information

    • Project URL - Enter any new project URL into the Project URL text box
    • CDDO API Id - Enter this into the CDDO API Id text box

  • Further information

    • Overview - Enter any new value into the Overview text box
    • Who can use - Enter any new value into the Who can use text box
    • Service level
    • Technologies
  1. Select the Save changes button. Or the Return to API metadata.

Viewing the metadata for a workspace Linked API

To view the metadata for your Linked API:

  1. Select Metadata from the left side menus tab. This will show you the API metadata detail page with details including Description, Data exposure classification. There is an Edit metadata link that allows you to make changes to the metadata associated with the API.

Documents

Documents relating to a Linked APIs can be uploaded and viewed within this page. These include guides on integration, consuming and testing the API.

Supported file formats are text and image files including PDF, JPG, and PNG.

Uploading documents for a workspace Linked API

To upload a documents for your Linked API document:

  1. Select Documents left side menus tab. This will show you the Documents page with listing on any previous uploaded documents.
  2. Select the Upload document link to the top right of the listings header. This will show you the Upload documents page and form.
  3. Enter a name for the document in the Document name text box.
  4. Enter a description for the document in the Description text box.
  5. Select the Choose file button to browse to the location of your document file.
  6. Select the document file.
  7. Select the Upload document button to upload and save the file. Or the Return to API documents link to cancel.

Viewing documents for workspace Linked API

To view a documents uploaded for a Linked API:

  1. Select Documents left side menus tab. This will show you the Documents page with listing of any previously uploaded documents. Alternatively, Select the Documents side menu option to expand the Documents menu tree option with list of any previously uploaded documents.
  2. Select the document name from the list of API documents. Alternatively, Select the name of the document from Documents menu tree. This will show you the View API document page with elements and details of the documents relating to your Limked API including:
  • Delete document button - Allows you to delete uploaded API documents.
  • Document name - Friendly name for the document which may be fiferent from the file name.
  • Description - Short description of what the document is about.
  • Original file name - Name of the actual API document file.
  • Download link - Allows download of the API document file.
  • File type - Type of file document being uploaded.
  • Last updated - Update date and timestamp to indicate when the file was uploaded.

Deleting documents uploaded for a workspace Linked API

To delete a Linked API document:

  1. Select Documents left side menus tab. This will show you the Documents page with listing on any previous uploaded documents. Or select the Documents side menu to open the Documents menu tree option with list of previous uploaded documents.
  2. Select the document name from the list of API documents. Or select the name of the document from Documents menu tree. This will show you the View API document page.
  3. Select the Delete document button. This will show you the Delete API document confirmation page.
  4. Select the Delete document button to confirm and delete the API document file. Or Return to API document link to cancel.

Downloading documents uploaded for a workspace Linked API

To download a Linked API document:

  1. Select Documents left side menus tab. This will show you the documents page with listing on any previous uploaded documents. Or select the Documents side menu to open the Documents menu tree option with list of previous uploaded documents.
  2. Select the document name from the list of API documents. Or, select the name of the document from Documents menu tree. This will show you the View API document page.
  3. Select the Download link next to the Original file name. This will show you the Download API schema page.
  4. Select the location to save the downloaded file.
  5. Select Download schema button to download and save the schema file. Or the Return to API overview to cancel.

Releases

The Release page provides you with information about the available releases for an API including:

  • Name - The name given to the API.
  • Lifecycle tag - This is a tag used to indicate the stage of an API within the release lifecycle (Planned, Alpha, Beta, Deprecated). See API Release Lifecycle Tags Statuses.
  • Available from - Date from which the release is available for use.
  • Available to - Date to which the release is available for use.
  • Current release - Indicates if the release is set as the current release for the API. Check to indicate 'Yes' or 'No'
  • Release notes - Any notes giving users further information about the release. This can include who can use the release, service level, or technologies.

There is a "Create new release" link at the top of release listing for creating or adding a new release for an API. Additionally, there are "View" and "Delete" action links allowing you to view release details for an API or delete an API release respectively.

Creating a release for a workspace Linked API

To create and add a new release for your Linked API:

  1. Select Releases from the left sidebar menus tab. This will show you the API release page with the list of releases along with release information including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes.
  2. Select the "Create new release" link at the top right of the listings table. This will show you the Edit release page with the Release information form to enter details including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes for the new release.
  3. Enter the following release information for your new API release:
  • a unique name and version identifier into the Name text box.
  • a tag from the Lifecycle tag dropdown options (Planned, Alpha, Beta, Deprecated).
  • an available from date for the API release into the Available from set of boxes in the format "DD MM YYYY".
  • an available to date for the API release into the Available to set of boxes in the format "DD MM YYYY".
  • indicate if the release is to be set as the current release by selecting the Current release checkbox, if it is. Selecting the checkbox will set the release as the current release to be used as default.
  • add any relevant notes to accompany the release into the Release notes textbox.
  1. Select the Save changes button. Or the Return to releases link to cancel.

Editing release information for a workspace Linked API

To edit release information for your Linked API release:

  1. Select Releases from the left sidebar menus tab. This will show you the API release page with the list of releases along with release information including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes.
  2. Select the "Edit" link next to release listings you want to edit. This will show you the Edit release page with the Release information form to enter updated details including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes for the existing release.
  3. Edit the relevant release information for your API including:
  • Name and version identifier into the Name text box.
  • Lifecycle tag from the Lifecycle tag dropdown options (Planned, Alpha, Beta, Deprecated).
  • the available from date for the API release by changing any existing values in the Available from set of boxes in the format "DD MM YYYY".
  • the available to date for the API release by changing any existing values in the Available to set of boxes in the format "DD MM YYYY".
  • indicate if the release is to be set as the current release by selecting the Current release checkbox, if it is. Selecting the checkbox will set the release as the current release to be used as default.
  • Any relevant notes for the release by changing any existing notes in the Release notes textbox.
  1. Select the Save changes button. Or the Return to releases link to cancel.

Viewing releases for a workspace Linked API

To view the releases for your Linked API:

  1. Select Releases from the left sidebar menus tab. This will show you the API release page with a list of releases along with release information including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes.

Deleting a release for a workspace Linked API

To delete a releases for your Linked API:

  1. Select Releases from the left sidebar menus tab. This will show you the API release page with the list of releases along with release information including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes.
  2. Select the "Delete" link next to release listings you want to delete. This will show you the Delete release page with release information including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes for the release.
  3. Select the Delete release button. Or the Return to releases link to cancel.

Viewing release information for a workspace Linked API

To view the releases information for your Linked API:

  1. Select Releases from the left sidebar menus tab. This will show you the API release page with the list of releases along with release information including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes.
  2. Select the "View" link next to release listings you want to view detailed release information. This will show you the API release detail page for that API release with information including name and version identifier, Lifecycle tag (Planned, Alpha, Beta, Deprecated), current release indicator, available from date, available to date, and any release notes for the release.
  3. Select the Return to releases link to return to the API release listings page.

Environments

Provides you with an environment to point your APIs including:

  • Dev - Development environment where developers can build, test and iterate on APIs.
  • Staging - Replica of a production environment that you can use to test your API build and updates to ensure quality and performance in a production environment before public deployment.
  • Live - Production release environment where you can publish your fully tested and approved API for the public to access and consumed.

Viewing environments for a workspace Linked API

To view a Linked API environment:

  1. Select the Environments left side menus tab. This will show you the API environments page with listing on availiable environments. Or, select the Environments side menu to expand the Environments menu tree option with list of available environments.
  2. Select the environment name from the list of API environments. Or, select the name of the API environment from Environments menu tree option. This will show you the API environments page with details of the available API environments including:
  • Name (Dev, Staging or Live)
  • Base URL (If none assigned, it will show 'Not configured')
  • Status (If none assigned, it will show 'Empty')

Configuring an environment for a workspace Linked API

To configure a Linked API environment:

  1. Select the Environments left side menus tab. This will show you the API environments page with listing on availiable environments. Or select the Environments side menu to expand the Environments menu tree option with list of available environments.
  2. Select the API environment name from the list of API environments. Or, select the name of the API environment from Environments menu tree option. This will show you the API environments page with details of the available API environments.
  3. Select the API environment you want to configure. For example, Dev. This will show you the API environment page with details including:
  • Environment name - Name assigned to the environment to identify and differentiate it from others (Dev, Staging or Live).
  • Status - Condition or state of an environment.
  • Base URL - Location of the API environment.
  • Change link - Allows you to change the Base URl for the API environment.
  1. Select the Change link next to the Base URL entry (which will show 'Unconfigured'). This will show you the Change API environment URL page with a Base URL text box.
  2. Enter a string for the location of API environment into the Base URL text box.
  3. Select the Save changes button to submit and save the Base URL. Or the Return to API environment link to cancel.

Once the Base URL is saved, it will appear as a link that can be selected when published.

Changing an Environment URL for a workspace Linked API

To change a Linked API environment URL

  1. Select the Environments left side menus tab. This will show you the API environments page with listing on availiable environments. Or select the Environments side menu to expand the Environments menu tree option with list of available environments.
  2. Select the API environment name from the list of API environments. Or, select the name of the API environment from Environments menu tree option. This will show you the API environments page with details of the available API environments.
  3. Select the API environment you want to configure. For example, Dev. This will show you the API environment details page with details including:
    • Environment name - Name assigned to the environment to identify and differentiate it from others (Dev, Staging or Live).
    • Status - Condition or state of an environment.
    • Base URL - The location of the API environment.
    • Change link - A link that allows you to change the Base URl for the API environment.
  4. Select the Change link next to the Base URL entry (which will show 'Unconfigured'). This will show you Change API environment URL page with the current base URL in the Base URL text box.
  5. Enter a new string for the location of API environment into the Base URL text box to replace the current base URL.
  6. Select the Save changes button to submit and save the updated base URL. Or the Return to API environment link to cancel.

Operations

These defines the path and methods that is used to perform a task including GET, POST, PUT, DELETE, and PATCH. The Operations page have details including:

  • Method - API method to perform a specific task. For example, GET to retrieve information.
  • Description - Describes what the API does and returns.
  • URL template - Specifies a URL that includes parameters that must be replaced before the URL is valid. The Operations page effectively shows what the methods and operations are contained within the schema file.

Changing the Name of a workspace Linked API

You can change the name of your Linked API by simply following the steps outlined in Editing metadata for a workspace Linked API

Changing the Description of a workspace Linked API

You can change the description for your Linked API by simply following the steps outlined in Editing metadata for a workspace Linked API

Removing a Linked API from a workspace

To remove a Linked API from a workspace:

  1. Select the API name link from the API section of the workspace Overview page. This will show you the API details page.
  2. Select the Overview menu option for the API. This will show you the API Overview page.
  3. Select the Delete API button at the botton of the API detail. This will show a message asking you to confirm that you want to delete the API from the workspace.
  4. Select Delete link to confirm and delete the API from the workspace.

Publishing a Linked API from a workspace

You can publish a Linked API from a workspace to your desired environment (Dev, Staging or Live) by following these steps:

  1. Select the My workspace link from the top navigation menu or the task link options within the body of the Home page. This will take workspace listing page.
  2. Select the API name link from the API section of the workspace Overview page. This will show you the API details page.
  3. Select the Overview menu option for the API. This will display the Publish sub-menu option.
  4. Select the Publish option. This will show you the Publish API page and perform a validation of information entered and configuration. This checklist will include:
  • Data exposure classification
  • Release version
  • Overview text
  • Schema document
  • API Environment configuration
  • APIM Policies And where validation fails with an error or warning, you can simply select the linked Publishing checklist item to take you to the relevant page to correct any invalid configuration.
  1. Review the list of changes you are about to make by viewing the change list comparing the existing and new configurations covering the different section and environments within the Compare changes section. Select the arrow to expand or hide comparison details.
  2. Review and confirm any Personal Identifiable Information (PID) exposure to users from using your API. This is to comply with data protection legislation including the standards outlined in the links to Personal data and The DfE's data protection hub provided on the page.
  3. Select Publish API to confirm and publish the API to the Find and Use an API Consumption Portal ready for users. Or the Return to API overview link to cancel.

There is a message to warn you about replacing any existing version of the API you are about to publish.

You can read the Guidance on API standards which tells you the standards expected for any API to be added to the DfE Catalogue ata anytime.

If you select the option declaring that your API may expose Personal Identifiable Information (PID), then you must select the checkbox to confirm that you have read and understood the standards outlined in both the Personal data and The DfE's data protection hub before you will ba allowed to publish your API. Once you publish your API, the Status entry within the API's detail page will appear as 'Publishing'

Unpublishing a Linked API from a workspace

You can unpublish a Linked API from a workspace by following these steps:

  1. Select the My workspace link from the top navigation menu or the task link options within the body of the Home page. This will take workspace listing page.
  2. Select the API name link from the API section of the workspace Overview page. This will show you the API details page.
  3. Select the Overview menu option for the API. This will show you the API details as part of the overview.
  4. Select the Unpublish link next to the Published version detail. This will show you the Unpublish API page.
  5. Select the Unpublish button to unpublish the API. Or the Return to API overview link to cancel.

Unpublishing an API will permanently remove that API from the DfE's Find and Use an API Consumption Portal and all related user content including Subscriptions and Authentication credentials will be lost.