APIs

Overview

Developer Portal offers you an exclusive platform to safely expose your APIs to your target developers and partners.

Developer Portal also allows developers to self-register, learn about these APIs, and use the APIs in their applications.

To prepare to manage the APIs that you plan to make available in Developer Portal, consider the following questions:

For each Developer Portal instance, there is a Developer Portal object registered with the API Provider. A Developer Portal is associated with an organization. Multiple Developer Portal instances can share the same organization.

An API can be published to multiple Developer Portal instances. Developer Portal is capable of managing APIs published from API Gateway or any other provider application.

When an API is unpublished (removed) from Developer Portal, its metadata is deleted from Developer Portal, and the API is no longer available for access.

In addition to APIs published from a provider, you can also create APIs in Developer Portal by providing a corresponding specification. The APIs created in Developer Portal need not be associated with any providers.

You can download the published APIs from Developer Portal to have a copy of the API specification.

How do I create an API?

You can create an API using a file, URL, or by providing the source content.

Developer Portal supports the publishing of OData APIs from provider applications such as API Gateway. However, you cannot create OData APIs in Developer Portal by providing a specification.

This use case starts when you want to create an API and ends when you have successfully created an API.

Before you begin:

Ensure that you have the file, URL, or the required content for creating the API.

In this example, you create an API Petstore using the https://petstore.swagger.io/v2/swagger.json URL. The API is assigned to the provider, Provider1 and the community, Mobile_app_developer.

To create an API

  1. Click the menu options icon from the title bar and click Manage assets.

  2. Click APIs.

  3. Click Create API.

  4. Provide Petstore in the Name field.

  5. Select Swagger from the Type list.

  6. Select Provider1 in the Provider field.

  7. Select Mobile_app_developer from the Community field.

  8. Select URL from the Import with section and provide https://petstore.swagger.io/v2/swagger.json in the field.

  9. Click Create.

    The API is created. You can view the API from the API gallery page and the Manage APIs page.

Alternative steps

  1. In Step 4, select any of the following API types from the Type list:

    • Open API. To create a REST API using an Open API specification.

    • RAML. To create a REST API using a RAML specification.

    • WSDL. To create a SOAP API using a WSDL specification.

  2. In Step 7, select the required provider.

    If you are creating the API for a third-party API gateway, ensure that the gateway is registered for the value to be available in the Provider field.

  3. In Step 7, provide the following inputs to create an API from the Import with section:

    • File. To create API from a file. Click Browse and select the required file.

    • Content. To create API from the given content. Provide the required parser content using which the API has to be created. Ensure that the content does not have references to external files.

Next steps:

How do I edit the basic attributes of an API?

Basic attributes of APIs include the API name, description, type, providers and communities associated with an API, and the API source.

This use case starts when you want to edit the basic attributes of an API and ends when you save your changes.

In this example, consider renaming the Pet_v1 API as Petstore_v1.

To edit the basic details of an API

  1. Click the menu options icon from the title bar and click Manage assets.

  2. Click APIs.

    The list of APIs appears.

  3. Click the edit icon next to the Pet_v1 API.

  4. Click Save.

    Your changes are saved. The API is removed from the public community. So, only the users who are a part of the Mobile_app_developer community can view or try the API.

How do I edit the advanced attributes of an API?

Advanced attributes of APIs include the API logo or icon, supporting documents, categories, and summary and description of the API resources.

Developer Portal supports providing of Markdown text and text in the supported languages for the following API attributes:

Note: For security reasons, it is recommended that you add authentic and valid Markdown content.

Sample Markdown text:

This use case starts when you want to edit the advanced attributes of an API and ends when you saved your changes.

In this example, consider adding API tags under API categories of the API, Petstore.

To edit the advanced details of an API

  1. Click the menu options icon from the title bar and click Manage assets.

  2. Click APIs.

    The list of APIs appears.

  3. Click the enrich icon next to the API that you want to edit.

  4. Select API categories from the left pane and provide the new tag, Swagger and press Enter.

  5. Click Save.

    The tag is added to the API. Users can filter APIs based on tags in the API gallery page.

Alternative steps

How do I create a new version of an API?

When you create a new version of an API, the API gallery page displays the latest version of the API. You can view all versions of the from the Manage APIs page. The API details page has a drop-down list that displays all API versions.

You can create new versions of an API for the use of a different set of consumers or with different security policies. New data can also be updated to the existing meta-data when you create new versions of your APIs.

The new API has the same metadata but with an updated version. The version can either be a number or a string.

Different versions of an API can be added to different communities and can be associated with different packages.

This use case starts when you want to create a new version of an existing API and ends when you created a new version of an API.

In this example, consider creating a new version of the API, Petstore 2.0 and map the newer version to the Public community.

To create a new version of an API

  1. Click from the title bar and click Manage assets.

  2. Click APIs.

    The list of APIs appear.

  3. Click the version icon next to the API, Petstore.

  4. Provide 2.0 in the Version field.

  5. Select Swagger from the Type list.

  6. Select Provider1 in the Provider field.

  7. Select Public from the Community field.

  8. Select URL from the Import with section and provide https://petstore.swagger.io/v2/swagger.json in the field.

  9. Click Save.

    A new version of the API, Petstore is created.

    Note: When you version an API, you can create versions from the newer version of the API and not from the older version.

    In the example, note that the older API does not have the version icon appearing next to it.

Alternative steps

  1. You can update the API by uploading a new file or by providing a new URL or pasting new content.

  2. You can also map the API to another provider.

Next steps

Trying APIs

Developer Portal allows you to try an API with required parameters.

You can try the required resource of an API by providing corresponding parameter values. You must also provide sufficient authorization details to have access to the API.

As an API consumer, it is important to test the endpoints of an API before putting them to use. Hence, Software AG recommends that you always test an API before consuming.

Trying a REST API

This section explains how you can test a REST API.

Pre-requisites

If the API that you are trying is protected with API key, JWT, or OAuth, then create an application to establish your identification. For information about creating applications, see Creating an application.

To try a REST API

  1. Navigate to the Try API page using one of the following ways:

    • Click the Tryout icon in the corresponding API tile. Or,

    • Click Try API from the API details page of the corresponding API.

    The Try API page appears. The resources that you can test appear in the left pane.

  2. Select a resource and the required method.

  3. Provide the following values in the Parameters tab:

    • Key. Key value of the parameter.

    • Value. Value of the corresponding key parameter.

    You can click Add new and add multiple entries.

  4. Provide the following required values in the Headers tab:

    • Key. Value of the header key.

    • Value. Value of the corresponding key parameter.

    You can click Add new and add multiple entries.

  5. Provide the authorization details from the Authorization tab.

    For information about the authorization types and required inputs, see Authorization fields.

  6. Select the required request form from the Request body tab and provide your request:

    • form-data. To send your request in the form of the key-value pairs. You can select Text and provide your form key and value or select File and attach the request file.

    • x-www-form-encoded. To send your request in the form of the encoded key-value pairs.

    • raw. To provide any request. You can provide the request in JSON or XML format.

    • None. To send the test request without a request body.

  7. Click Send.

    The response body and headers appear in their respective sections.

Trying a SOAP API

This section explains how you can test a SOAP API.

Pre-requisites

If the API that you are trying is protected with API key, JWT, or OAuth, then create an application to establish your identification. For information about creating applications, see Creating an application.

To try a SOAP API

  1. Navigate to the Try API page using one of the following ways:

    • Click the Tryout icon in the corresponding API tile. Or,

    • Click Try API from the API details page of the corresponding API.

    The Try API page appears. The SOAP methods that you can test appear in the left pane.

  2. Select the required method.

  3. Provide the following values in the Parameters tab:

    • Key. Key value of the parameter.

    • Value. Value of the corresponding key parameter.

    You can click Add new and add multiple entries.

  4. Provide the required header details from the Headers tab:

    To include header key value combinations, provide the following:

    • Key. Value of the header key.

    • Value. Value of the corresponding key parameter.

      You can click Add new and add multiple entries.

    To include a SOAP header:

    • Name. A unique name to distinguish the provided SOAP headers, if there are multiple headers.

    • Click Add new namespace URI to provide unique Key elements and corresponding Value attributes for the header content. You can provide multiple key and value combinations by clicking Add new namespace URI.

    Header content.

    You can click Add SOAP header to provide more headers.

  5. Provide the authorization details from the Authorization tab.

    For information about the authorization types and required inputs, see Authorization fields.

  6. If the SOAP API is protected with web service security (WSS) select the required authorization method from the Web Service Security tab:

    • WSS user token. Select this to provide WSS user name and password.

    • Provide the user name and password required for WSS authorization.

    • Select the Add nonce check box to include nonce, which is a randomly generated number that is included in the request header sent to the API server. Nonce is generated every time a request is sent to the API server and thus, adding a nonce to the request along with WSS user token prevents reuse of old communications.

    • Select the Add creation time check box to add a timestamp that the nonce was created. This value helps server to ensure that the outdated nonce values are not reused.

    • Select Password text to send password as plain text. Else, select Password digest to encrypt the password.

    • WSS SAML assertion. Select this to include SAML assertion for WSS authorization. You can either paste the assertion or upload the assertion file.

    You can include both, WSS user token and SAML assertion, in your request. You can select either of these options, provide the required details, and then the other option without pressing Clear. So, the details provided for both options are included to the request.

  7. In the Request body tab, provide your request in the form of key-value pairs or raw text.

  8. Click Send.

    The response body and headers appear in their respective sections.

Trying a OData API

This section explains how you can test a OData API.

Pre-requisites

If the API that you are trying is protected with API key, JWT, or OAuth, then create an application to establish your identification. For information about creating applications, see Creating an application.

To try a OData API

  1. Navigate to the Try API page using one of the following ways:

    • Click the Tryout icon in the corresponding API tile. Or,

    • Click Try API from the API details page of the corresponding API.

    The Try API page appears. The resources that you can test appear in the left pane.

  2. Expand the required resource and click the required method.

  3. In the Query builder tab, select the required query parameters and click Add.

    The specified parameters are included as a query in the request URL.

  4. Provide the following values in the Parameters tab:

    • Key. Key value of the parameter.

    • Value. Value of the corresponding key parameter.

    You can click Add new and add multiple entries.

  5. Provide the following required values in the Headers tab:

    • Key. Type a header key value.

    • Value. Type the corresponding value of the key parameter.

    You can click Add new and add multiple entries.

  6. Provide the authorization details from the Authorization tab.

    For information about the authorization types and required inputs, see Authorization fields.

  7. Select the required request form from the Request body tab and provide your request:

    • form-data. To send your request in the form of the key-value pairs. You can select Text and provide your form key and value or select File and attach the request file.

    • x-www-form-encoded. To send your request in the form of the encoded key-value pairs.

    • raw. To provide any request. You can provide the request in JSON or XML format.

    • None. To send the test request without a request body.

  8. Click Send.

    The response body and headers appear in their respective sections.

Authorization fields

This section lists the steps to provide authorization details, for testing APIs, based on the authorization type applied to the corresponding APIs:

Authorization type Procedure
For APIs protected with API key
  • Select the required application from the Applications field.

  • Select API Key from the Authorization type field.
The test request is sent to the API server with the API key of the selected application.
For APIs that require basic authentication
  • Select Basic auth from the Authorization type field.

  • Provide the user credentials and click Update.
The test request is sent with the selected authorization details.
For APIs protected with JWT
  • Select the required application from the Applications field.

  • Select JWT from the Authorization type field.
    The JWT tokens available for the selected application appear in the Available tokens section. You can select a token from the list or request for a new one.
  • Click to get a new access token. The Create new token page appears.

  • Provide the credentials associated with the JWT authorization and click Get token.
    The token appears in the Available token section. Validity of token’s are based on the duration specified in API Gateway.
  • Select the created token.
    The test request is sent to the API server with the selected token details.
For APIs protected with OAuth
  • Select the required application from the Applications field.

  • Select OAuth 2.0 from the Authorization type field.
    The tokens available for the selected application appear in the Available tokens section. You can select a token from the list or request for a new one.
  • Click to get a new access token.
    The Create new token page appears.

  • Provide a Token name.

  • Select the required Grant type and the required scope.

  • Click Get token.
If you had selected the Authorization code or Implicit grant type, the webMethods API Gateway Resource access approval page appears.
  • Select the required scopes and click Approve.

  • Provide your API Gateway credentials and click Sign in. You will be redirected to Developer Portal Try API page. The token appears in the Available token section. Validity of token’s are based on the duration specified in API Gateway.

  • Select the created token.
If you had selected Client credentials grant type, then the request token appears without any further action.
  • Select the created token.
The test request is sent to the API server with the selected token details.
For APIs that do not require any authentication
  • Select None from the Authorization type field.
The test request is sent to the API server without any authorization.