In this section, you will be guided through the process of managing Hosted 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 Find and Use an API Management Portal.

Adding a Hosted API to a workspace

To add a Hosted 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 Hosted 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 and differentiate the API from others you may add.
  5. Enter a codename for the API into the API codename text box. This forms part of the URL used by subscribers to access the API endpoint. The codename can contain lower case characters and hyphens only. It is worth noting that the requirement for a codename is one of the primary differences between the fields to be completed for adding a Hosted API to that for a Linked API.
  6. Enter a description into the Description text box.
  7. Select the API Backend type from the dropdown options (currently HTTP or SOAP).
  8. Select the Version scheme from the dropdown options (URL Suffix or None). See version scheme
  9. Enter the version identifier number into the Major version identifier text box.
  10. Select the Save API button to add the API or the Return to workspace overview link to cancel. Upon adding the Hosted API, you will be taken to the API details page for the newly added API where you will have menu options including:
  • Overview
  • Metadata
  • Documents
  • Releases
  • Environments
  • Operations
  • Authentication (Available for Hosted API only)
  • Policies (Available for Hosted API only)
  • Subscriptions (Available for Hosted API only)

Overview

The overview page for Hosted API will have details of the workspace including:

  • API type (Hosted)
  • Backend type (HTTP, SOAP or GraphQL)
  • Visibility (Private, DfE Internal or Public)(Private, DfE Internal or Public) See more details here
  • Schema (Mandatory) - including a Change link allows you to upload an OpenAPI or Swagger schema for the API. This generates all the operations and allow users within the Consumption portal can see what the API does. Additionally, a Download link that allows you to download the API schema.
  • Status (Published or Draft) - See more details here
  • Published version (including a Publish link to publish the API and Unpublish link)
  • Subscription count (valid for Hosted API only) - This is a count of all subscribers to that API subscription.

By default, all APIs added to a workspace and published to the DfE Find and Use an API Catalogue have their visibility setting as 'Private', so you will need to change this public if you want an API visible to all users.

Changing the Visibility of a workspace Hosted API

To change the Visibility of your Hosted 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 Hosted API

To change the schema for your Hosted 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 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 Hosted API

To view the schema file for your Hosted 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 Hosted API

To preview changes and impact on an API operation scope policy due to a new schema file upload for your Hosted 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 the operation name, description and method.
  • Verify schema import - showing details including Schema type, Schema file
  • Operations section - showing details including the method, description, 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 file for a workspace Hosted API

To Download the schema for your Hosted 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 clasiification (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 Hosted API

To add metadata to your Hosted 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 Hosted API

To edit metadata for your Hosted 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 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 Hosted API

To view the metadata for your Hosted 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 Hosted 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 Hosted API

To upload a documents for your Hosted 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 Hosted API

To view a documents uploaded for a Hosted 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 Hosted API

To delete a Hosted 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 Hosted API

To download a Hosted 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 Hosted API

To create and add a new release for your Hosted 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 Hosted API

To edit release information for your Hosted 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 Hosted API

To view the releases for your Hosted 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 Hosted API

To delete a releases for your Hosted 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 Hosted API

To view the releases information for your Hosted 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 to your APIs including:

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

Viewing a Hosted API environment

To view a Hosted 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 display 'Not configured')
  • Status (If none assigned, it will display 'Empty')

Configuring a Hosted API environment

To configure a Hosted 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 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.
  • Auto-approval - Indicates if auto-approval of subscription request to the API is enabled.
  • Enable link - Used to enable or disable Auto-approval
  • Base URL - Location of the API environment. However, this is not usually required for API's hosted on the DfE Find and Use an API service.
  • Backend URL - Location address of the backend server for the hosted API environment. Required for Hosted APIs only - another difference between the required configuration for a Hosted and that for a Hosted API.
  • Change link - Allows you to change the Backend URL for the Hosted API environment.
  1. Select the Change link next to the Base URL entry (which will show 'Unconfigured'). This will show you 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.

Changing a Hosted API environment Backend URL

To change a Hosted API environment Backend 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.
  • Auto-approval - Indicates if auto-approval of subscription request to the API is enabled.
  • Enable link - A link to enable or disable Auto-approval
  • Base URL - The location of the API environment. However, this is notusually required for API's hosted on the DfE service.
  • Backend URL - Location address of the backend server for the Hosted API environment. Required for Hosted APIs only - another difference between the required configuration for a Hosted and that for a Hosted API.
  • Change link - Allows you to change the Backend URL for the Hosted API environment.
  1. Select the Enable link next to the Auto-approval entry. This will show you the Auto-approval confirmation page.
  2. Select the Save changes button to submit and save the updated Backend URL. Or the Return to API environment link to cancel.

Setting subscription auto-approval for a Hosted API

To set subscription auto-approval for a Hosted API:

  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 left 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. Alternatively, 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.
  • Auto-approval - Indicates if auto-approval of subscription request to the API is enabled.
  • Enable link - Allows you to enable or disable Auto-approval.
  • Base URL - Location of the API environment. However, this is not required for Hosted APIs. See types of APIs
  • Backend URL - The location address of the backend server for the hosted API environment. Required for Hosted APIs only- another difference between the required configuration for a Hosted and that for a Hosted API.
  • Change link - A link that allows you to change the Backend URL for the Hosted API environment.

Operations

These defines the path and methods that is used to perform a specific task including GET, POST, PUT, DELETE, and PATCH. You will find the following details on Operations page 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 the parameters that must be replaces before the URL is valid.

The Operations page effectively shows what the methods and operations contained within the schema file.

Changing the Name of a workspace Hosted API

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

Changing the Description of a workspace Hosted API

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

Removing a Hosted API from a workspace

You can remove an API from a workspace by following these steps:

  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 you a message to confirm you want to delete that API from the workspace.
  4. Select the Delete button to confirm and delete the API from the workspace. Or the Return to API overview link to cancel.

Publishing a Hosted API from a workspace

To publish a Hosted 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 show you 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 configuraton
  • 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 Hosted API from a workspace

You can unpublish a Hosted 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.

Authentication

Provides you with a way to configure an authentication method for your Hosted API. This page will have a list of authentication methods and details. There are two types of authentication methods that can be added to a Hosted API. You cannot publish an API without at least one authentication method configured for it.

1. Subscription key authentication method

The subscription key method listing will have details and links including:

  • Add an authentication method link - Allows you to configure an authentication method.
  • Edit link - Allows you to add or edit a subscription key.
  • Delete link - Allows you to delete a subscription key.
  • Enabled - Indicates if a Subscription key is mandatory (Yes or No).
  • Auto-enforcement - Indicates if Subscription key and an authentication method is mandatory. Hence, the API cannot be accessed without a valid Subscription key.
  • Header name - The name of the API request header parameter which value are then assigned to.
  • Query parameter name - The name of the request query parameter name which values are assigned to.

When you add a new Hosted API to a workspace, it will automatically have the following default values which you can then edit:

  • Enabled - Set to 'Yes'.
  • Auto-enforcement - Set to 'Yes'.
  • Header name - Assigned the value 'Ocp-Apim-Subscription-Key'
  • Query parameter name - Assigned the value 'subscription-key'

2. Native OAuth Application-flow authentication method

The Native OAuth Application-flow method listing will have details and links including:

  • Enabled - Indicates if a Native OAuth Application-flow is mandatory ('Yes' or 'No').
  • Auto-enforcement - Indicates if a Native OAuth Application-flow and an authentication method is mandatory. This means the API cannot be accessed without completing a valid Native OAuth Application-flow.
  • Exclusion path - This provide more control on authentication requirement. This means you can permit API accessed without completing a valid Native OAuth Application-flow on specific request path and mandatory valid on on other paths - allowing a secure and less secure area within the API access and use. This parameter is optional, so you can just leave it blank.

You can use wildcards as part of you path setting and this would form part of the filter criteria when enforcing authentication requirement.

  • Custom OAuth scopes (Mandatory) - List of permissions granted to the subscriber or user of the API. For example, 'Read' permission.
  • OAuth token endpoint - Location URL provided by the OAuth token issuer and for performing the Native OAuth Application-flow authentication to obtain a valid token.

Adding an authentication method to a Hosted API

To add an authentication method to a Hosted API: As previously mentioned, by default, all new APIs are assigned a Subscription key authentication method, with default Subscription key values, as these are mandatory settings for Hosted APIs.

However, additional API authentication methods can be added including Native OAuth Application-flow.

Adding an additinal authentication method to a Hosted API

To add an additinal authentication method to a Hosted API: You can do this be following these steps:

  1. Select Authentication from the left side menus tab. This will show you the API authentication methods page with a Add an authentication method link. This will show you the Add API authentication method page.
  2. Select the authentication method you want to add from the options shown to you (Subscription key or Native OAuth Application-flow).
  3. Select the Save changes button to save and add the authentication method. Or the Return to API authentication link to cancel.

Adding a subscription key to a Hosted API

As previously mentioned, all new API are assigned default values to mandatory setting for authentication method and Subscription key details. These default values can be replaced to add a new Subscription key.

To add a subscription key to a Hosted API:

Just replace default values by following the steps outlined in the To edit subscription key for a Hosted API for a Hosted API)

Editing a subscription key for a Hosted API

To edit subscription key for a Hosted API:

  1. Select Authentication from the left side menus tab. This will show you the API authentication methods page.
  2. Select the Edit link next to the Subscription key heading. This will show you the Edit API aunthentication method page and form.
  3. Enter the setting and values for Enabled, Auto-enforcement, Header name, and Query parameter name.
  4. Select Save changes button to save and add the new details. Or the Return to API authentication link to cancel.

Once new subscription key details are updated, any API schemas or integrations uisng the old API subscription key settings and details including Header name and Query parameter name will stop working.

Deleting a subscription key for a Hosted API

To delete a subscription key for a Hosted API:

  1. Select Authentication from the left side menus tab. This will show you the API authentication methods page.
  2. Select the Delete link next to the Subscription key heading. This will show you the Delete API aunthentication method page.
  3. Select the Delete button to delete the subscription key for the Hosted API. Or the Return to API authentication link to cancel.

Once subscription key is deleted, any API subscriptions using that key will not work and any requests will fail.

Adding a Native OAuth Application-flow for a Hosted API

To add a Native OAuth Application-flow for a Hosted API:

  1. Select Authentication from the left side menus tab. This will show you the API authentication methods page.
  2. Select the Edit link next to the Native OAuth Application-flow heading. This will show you the Edit API aunthentication method page and Native OAuth Application-flow form.
  3. Enter the desired setting and values for Enabled, Auto-enforcement, and Custom OAuth scopes.
  4. Select Save changes button to save and add those details. Or the Return to API authentication link to cancel.

Editing a Native OAuth Application-flow for a Hosted API

To edit Native OAuth Application-flow for a Hosted API:

  1. Select Authentication from the left side menus tab. This will show you the API authentication methods page.
  2. Select the Edit link next to the Native OAuth Application-flow heading. This will show you the Edit API aunthentication method page and Native OAuth Application-flow form.
  3. Enter the desired setting and values for Enabled, Auto-enforcement, and Custom OAuth scopes.
  4. Select Save changes button to save and add those details. Or the Return to API authentication link to cancel.

Once Native OAuth Application-flow details are updated, any API schemas or subscriptions uisng the previous Native OAuth Application-flow settings and details will stop working.

Deleting a Native OAuth Application-flow for a Hosted API

To delete a Native OAuth Application-flow for a Hosted API:

  1. Select Authentication from the left side menus tab. This will show you the API authentication methods page.
  2. Select the Delete link next to the Native OAuth Application-flow heading. This will show you the Delete API aunthentication method page.
  3. Select the Delete button to delete the Native OAuth Application-flow for the Hosted API. Or the Return to API authentication link to cancel.

Once an Native OAuth Application-flow is deleted, any API subscriptions using permissions granted by that Native OAuth Application-flow will not work and requests will fail.

Policies

These are used to control various aspects of an API when presented to the public for consumption - through the Find and Use an API Consumption Portal. Policies are grouped into different scopes as indicated with the presentation of the Policies page.

  • API scope - Policy is applied at the API level
  • Environment scope - Policy is applied to a specific API environment (Dev, Staging or Live)
  • Operation scope - Policy is applied and affects only a specific operation. For example, GET method where the policy will only affect retrieving information operation using the API.

You can combine these policies into complex scopes that are broad or narrow in changing the behavour of a published API. For example, you can setup policy scopes that cover a specific API, all environment and only a specific operation.

Policies are optional when publishing your API. This means you can add policies for the different scopes, environments or none. Additionally, it is worth noting that each policy inherits from the policy scope above. This means Operations scope inherits from the Environments scope and the Environments scope inherits from the API scope.

API scope

This section contains details and links including:

  • Top-level API policy - Details of API level policy.
  • Edit link for Top-level API policy - Allows you to edit a Top-level API policy detail.

Editing an API scope policy

To edit an API scope policy:

  1. Select Policies from the left side menus tab. This will show you the API policies page with a list of Policy configurations.
  2. Select the Edit link next to the Top-level API policy. This will show you the **Edit API policy ** page.
  3. Enter the relevant policy definition expression into the Policy definition text box.
  4. Select Save changes button to save and add the details. The Reset to default link to revert to default setting, or the Return to API policies link to cancel.

There is a Click here for guidance on API policies link at the top of the form, so you can read guidance notes at anytime.

The default policy definition - which effectively means no policy may look like this:

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Deleting an API scope policy

To delete an API scope policy:

  1. Select Policies from the left side menus tab. This will show you the API policies page with a list of Policy configurations.
  2. Select the Delete link next to the Top-level API policy. This will show you the **Delete API policy ** page.
  3. Select Delete button to delete the API scope policy. Or the Return to API policies link to cancel.

There is a Click here for guidance on API policies link at the top of the form, so you can read policy guidance notes at anytime.

Environment scope

This section contains details and links including:

  • Dev policy - Details of Dev environment scope policy.
  • Edit link for Dev - Allows you to edit a Dev environment scope policy detail.
  • Staging policy - Details of Staging environment scope policy.
  • Edit link for Staging - Allows you to edit a Staging environment scope policy detail.
  • Live policy - Details of Live environment scope policy.
  • Edit link for Live - Allows you to edit a Live environment scope policy detail.

Editing an Environment scope policy

To edit an Environment scope policy:

  1. Select Policies from the left side menus tab. This will show you the **API policies ** page with a list of Policy configurations.
  2. Select the Edit link next to the environment (Dev, Staging or Live) you want to edit the API scope policy. This will show you the **Edit API policy ** page.
  3. Enter the relevant policy definition expression into the Policy definition text box.
  4. Select Save changes button to save and validate the Environment scope policy. Or Reset to default link to revert to default setting, or the Return to API policies link to cancel.

On successful validation of a API policy expression, the Policy have a status of 'Valid'. Otherwise an error message and suggestion of what might be wrong with the policy express will be shown - and the Environment scope policy invalidated as indicated by an 'Invalid' status.

There is a Click here for guidance on API policies link at the top of the form, so you can read guidance notes at anytime.

The default policy definition - which effectively means no policy. A default policy definition may look like this:

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

If your API contains any invalid policies, you will not be able to publish the API into the Find and Use an API Catalogue.

Operation scope

This section contains details and links including:

  • GET (Get information policy) - Gives you details of operation scope policy.
  • Edit link for GET operation - Allows you to edit GET operation scope policy.
  • View resultant link for GET operation - Allows you to view the result of the GET operation scope policy.

Editing an Operation scope policy

To edit an Operation scope policy:

  1. Select Policies from the left side menus tab. This will show you the **API policies ** page with a list of Policy configurations.
  2. Select the Edit link next to the operation method you want to edit the Operations API scope policy. This will show you the **Edit API policy ** page.
  3. Enter the relevant operations API scope policy definition expression into the Policy definition text box.
  4. Select Save changes button to save and valid the policy, the Reset to default link to revert to default setting, or the Return to API policies link to cancel.

On successful validation of a Operations scope policy expression, the Policy have a status of 'Valid'. Otherwise an error message and suggestion of what might be wrong with the policy express will be shown and API Operations scope invalidated indicated by an 'Invalid' status.

There is a Click here for guidance on API policies link at the top of the form, so you can read guidance notes at anytime.

The default policy definition - which effectively means no policy may look like this:

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Viewing an Operation scope policy resultant

To view an Operation scope policy resultant:

  1. Select Policies from the left side menus tab. This will show you the API policies page with a list of Policy configurations.
  2. Select the View resultant link next to the operation method you want to edit the Operations API scope policy. This will show you the API operation resultant policy page.
  3. Select the relevant environment want to view a result from the Target environment dropdown list. And alllows you to see what will happen if a user called that particular operation through that method from the selected environment. This means it will combine the API scope policy, selected environment's scope policy and the Operations scope policy for that method to derive a resultant policy.

An example of a resultant policy definition may look like this:

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Subscriptions

The Subscriptions page provides a list and details of API subcriptions across all environments including:

  • Name - Friendly name of the API subscription.
  • Environment - The environment hosting the API subscription.
  • User - List of users subscribed to an API subscription.
  • Created at - Subscription created date and timestamp.
  • Action - The actions that can be perform on a subscription including disabling and deleting it. The Disable link allows the API Admin to disable a subscription and the Delete link allows an API Admin to delete the subscription.

Viewing an API's subscription detail

To view an API's subscription detail:

  1. Select Subscriptions from the left side menus tab. This will show you the API subscriptions page with a list of subscriptions.
  2. Select the Name link for the API subscription you want to view. This will show you the API subscriptions detail page with details including:
  • API type (Hosted)
  • Backend type (currently HTTP only)
  • Visibility including a Change link that allows you to change the visibility level. See more details on visibility here
  • Schema (Mandatory) including a Change link that allows you to upload new, or replace an existing OpenAPI or Swagger schema for the API. This generates all the operations and allow users within the Find and Use an API Consumption Portal to see what the API does. Additionally, a Download link that allows you to download the API schema.
  • Status (Published or Draft) - See more details on API publication statuses here
  • Published version (including a Publish link to publish the API)
  • Subscription count (valid for Hosted API)

Disabling an API subscription

To disable an API subscription within your workspace:

  1. Select Subscriptions from the left side menus tab. This will show you the **API subscriptions ** page with a list of subscriptions.
  2. Select the Disable link under Action column for the API subscription you want to disable. This will show you the **Disable API subscriptions ** page.
  3. Select the Disable button to disable that API subscription. Or the Return to API Subscription link to cancel.

Once a subscription is disabled, any existing integrations using the subscription will stop functioning immediately.

Deleting an API subscription

To delete an API subscription within your workspace:

  1. Select Subscriptions from the left side menus tab. This will show you the **API subscriptions ** page with a list of subscriptions.
  2. Select the Delete link under Action column for the API subscription you want to delete. This will show you the Delete API subscriptions page.
  3. Select the Delete button to delete that API subscription. Or the Return to API Subscription link to cancel.

Once the subscription is deleted, any existing integrations using the subscription will be denied access immediately. You will also lose both the Primary and Secondary keys associated with that subscription and the OAuth Client ID relating to any Native OAuth Application-flow. This cannot be reversed, so make sure you want to delete the subscription.

Searching API subscriptions

You can search for API subscriptions within your workspace using the search form above your subscription listing and by following these steps:

  1. Select Subscriptions from the left side menus tab. This will show you the API subscriptions page with a list of subscriptions and a subscriptions search form.
  2. Type a word or phrase for the subscrition you are searching for into the Search box. This search function allows you to search for any subscription. You will have the options to apply filtering and pagination before or after your search.
  3. Select the Search button under Action to submit your search. This will show you any found results.
  4. Select the relevant subscription from the result to view that API subscription detail.

Applying Filtering

You can apply filtering by workspace environment, or owner to any search.

Applying Pagination

You can change the number of results you wish returned per page using the Display results dropdown box option.

Applying pagination will add pagination controls 'Next' and 'Previous' links to the result display page.