API Publishing

Publish an API, configure license scope to determine what licenses will be offered for the API, and perform maintenance activities.

Table of Contents

  1. What are APIs?
  2. What is a private API?
  3. What are the recommended API development best practices?
  4. What is the minimum requirement for adding an API?
  5. What security and monitoring policies are supported?
  6. What is the minimum policy requirement for my API?
  7. How do I add an API?
  8. How do I add a new API (API with New Service)?
  9. How do I add an API from an existing API Gateway service (API with Existing Service)?
  10. What is scope mapping and how do I set it up?
  11. How do I inform app developers about available licenses and API access?
  12. How do I add a REST service?
  13. How do I manage API visibility?
  14. What is a proxy API?
  15. What is the difference between sandbox and production environments?
  16. What is an API Type Profile?
  17. What are the supported HTTP methods and content types for requests?
  18. What is Anonymous API Access?
  19. How do I add an API version?
  20. How do I edit an API?
  21. How do I export an API?
  22. What are the contents of the API export file?
  23. How do I import an API from an export file?
  24. How do I delete an API?
  25. How do I determine what licenses will be available for my API?
  26. How do I edit the license on an API access request?
  27. How do I see the status of my API's contracts with apps?

What are APIs?

APIs are business capabilities exposed over the internet for applications to use. Simply put, an API is a programming interface that your organization exposes over the internet that allows applications to communicate with your backend systems. Typically, you build APIs that expose specific aspects of business functionality. These are things that differentiate you in the market place and that make money for you and your company. So essentially what you are doing through the creation of APIs is creating a new channel for your business by exposing a set of capabilities for your product (i.e., services that people can build into mobile applications and sell to their customers), thereby creating a channel for your products and services online.

Back to top

What is a private API?

The platform supports public and private APIs. Public APIs are visible to members (users who have signed up and logged in) and visitors (users who have not yet signed up). Private APIs are visible only to platform users who are members of one or more groups that have been specifically invited to have visibility of the API.

In the platform, any API or other resource that is private is shown with a "lock" icon to indicate privacy.

Back to top

What are the recommended API development best practices?

Developing an API includes these key phases: Plan, Build, Run, and Promote.

Planning:

The planning phase involves determining which APIs to publish. Key considerations when selecting APIs include:

  1. Is the API well defined and well scoped?
  2. Does the API deliver a clear business value?
  3. Does the API highlight and showcase your differentiators as a company?
  4. Does the API offer your potential consumer with a clear business value and reason for using it?
  5. Does the API offer cost benefits or functionality over potential competitors?

Build:

After the API has been planned, approved and appropriately scoped, the next step is to build it. Jet considerations when building an API:

  1. Is the API atomic and well documented?

    Building an API that is simple, easy to understand, and well documented will encourage developers to use it.

Run:

After the API is built, the next step is to run it. Key considerations when running an API include:

Promote:

Once the API is running you must promote it. Key considerations when promoting an API include:

  1. How can you as an organization create a market for the API?

    Collaborate—To market your API to a set of consumers (i.e., developers writing applications) you must create a community around your API. Creating a community of partners provides a value add to your services and your APIs and allows developers to collaborate with each other. This can be accomplished in the platform using the API Group and API Board functions.

    Search—Users need to be able to effectively find your APIs, you need to get access to the documentation and collaborate around developing their applications. This can be accomplished in the platform using the Search function where users can perform a free text search or use a pre-defined search filter.

    Support—You must support the API effectively. As you write your APIs you may run into problems and would like gain expertise and advice from community members. This can be accomplished in the platform using the API Board, trouble ticket management system, and by submitting a support request.

Back to top

What is the minimum requirement for adding an API?

The minimum requirement to add an API to the platform is that it must have an endpoint. For example:

Back to top

What security and monitoring policies are supported?

The platform allows you to secure and monitor your APIs with the following pre-configured policies. These policies are selected by default and should be assigned to newly created APIs. Three policy categories are supported:

Policy Name Description
ApplicationSecurityUnsigned This is a default security policy for platform applications.

Policy Category: Simple Header Security

Policy Type: API Consumer Application Security

Configuration: No Signature checked.
ApplicationSecuritySigned This is a default security policy for Enterprise API Platform applications. It provides support for SHA1 (Shared Secret).

Policy Category: Simple Header Security

Policy Type: API Consumer Application Security

Configuration: Shared Secret checked
BasicAuditing Provides basic auditing of messages. Message metrics will be recorded in the Usage Logs Monitoring tab. The messages themselves will not be audited. That can be achieved using the DetailedAuditing policy.

Policy Category: Monitoring

Policy Type: WS-Auditing Service Policy

Configuration: Audit All Messages, Audit Message Size, Audit Identities (Consumer and End User), Reporting Options (Log)
DetailedAuditing Provides detailed auditing of messages. Message metrics will be recorded in the Usage Logs Monitoring tab as well as the entire messages of each exchange.

Policy Category: Monitoring

Policy Type: WS-Auditing Service Policy

Configuration: Audit All Messages, Audit Input Message, Audit Output Message, Audit Fault Message, Audit Message Size, Audit Binding, Audit Transport, Audit Contract, Audit Identities (Consumer and End User), Reporting Options (Log)
OAuthSecurity The OAuthSecurity Policy uses the OAuth configuration assigned to an API when enforcing OAuth tokens in the received request.

Note: Selection of this policy is typically assigned to an API after performing the Edit OAuth Details configuration on the API Details page in the Community Manager portal. Use Edit on the API Details page, go to the 3. Proxy page, and in the Advanced Options select OAuthSecurity in the Policy section.

Policy Category: OAuth

Policy Type: XML Policy

Configuration: Do not configure.

If you subscribe to an API Enterprise Management Platform or decide to install on-premises then you also have the ability to create and manage your own Policies. If you require a policy that is not on the default list, submit a support request..

Back to top

What is the minimum policy requirement for my API?

When you add an API using the Add a New API Wizard, in the Policies section on the Proxy page, you MUST select one security policy (e.g., Category: Simple Header Security) and you should select a monitoring policy if you want to see charts and logs. If no policies display, consult your API Provider or Site Administrator.

Back to top

How do I add an API?

Your ability to add an API, and the choices available to you, vary according to the configuration settings for the specific instance of the platform you are using.

If you have the applicable permission, you can add an API. Click the Plus Menu (the + icon at the top of the page) and choose Add a New API. For additional instructions, see How do I add a new API (API with New Service)? below.

In some cases, your version of the platform might be configured to allow you to either add an API by defining a new service, (SOAP-based or REST-based), or add an API for a service that's already defined in the API Gateway.

If this is your scenario—from the Plus Menu (the + icon at the top of the page), select Add a New API and you will see the Select Type of API overlay. Choose one of the following:

Note: If the above options are not available to you and you feel they should be, contact your Site Admin for assistance.

Back to top

How do I add a new API (API with New Service)?

The platform provides an Add a New API function that allows you to add a SOAP or REST-based API. APIs can be added for both Sandbox and Production environments.

Note: If you want to add an API from a service already defined in the API Gateway, use the Add API from Service option (if available) instead of Add a New API. For more information, see How do I add an API from an existing API Gateway service (API with Existing Service)? below.

Prerequisites:

The Add APIs Wizard includes the following sections:

API

On the API page you perform the initial step of specifying an API Name, Version ID, Tags, Visibility (Public/Private), API Description, Version Description, and API Icon. This information displays on your public API page which also displays in the API search results.

A platform user who performs a search and finds your public API page, sees the API description and can rate and write and review your API. Individuals can also participate in a Yes/No survey indicating whether a review was useful or not. Based on this high visibility it's important that your API description is highly informative and includes the necessary marketing, functional, and use case information that will engage customers to request access to your API.

Target

On the Target page, you can configure SOAP-based APIs by specifying the SOAP version and WSDL. REST-based APIs are configured by specifying one or more operations. Policy selection is not required for the Target URL.

Proxy

The Proxy API page allows you to configure your API's proxy settings. If you would like to proxy your API, select the Yes radio button in the Proxy API section. There are many benefits to proxying your API including utilizing platform security and service-level policies, monitoring performance, and allowing App Developers to gain access to your API sandbox endpoint (to test API functionality in their app), and production endpoint (to use API functionality in a live application). The Allow Anonymous Access option allows you to enable anonymous access to an API endpoint if you would like to offer a preview of an API to developers without requiring users to create an app or sign up to the platform. For more information, see What is anonymous API access?

To add a new API:

A. Launch the Add a New API Wizard

  1. From the Plus Menu, select Add a New API. The Select Type of API overlay appears.
  2. Choose API with New Service and click Create. The Add API Wizard displays at the first page.

Note: In some implementations, only a Business Administrator can add an API. If the option to add an API is not available to you and you feel it should be, contact your Administrator.

B. Specify API General Information

  1. On the API page, specify the API Name, Version ID, Tags, Visibility (Public/Private), API Description, Version Description, and API Icon for the API. All the information you specify here displays on your customer-facing API Details page.
  2. Define whether the API will use licenses. Click the Use Licenses checkbox to enable the licenses feature, including scope mapping. For more information, see What is scope mapping and how do I set it up?

C. Specify Target URL and Environment

  1. After specifying the API information, click Next to continue. The Target page displays. Here you will specify Target URL, select the Environment, and configure Advanced Options for your API.
  2. In the Target section, specify the Target URL (target endpoint) of the API implementation. If you would like to specify additional Target URLs, click Add URL. For example, you might add one URL for a Sandbox Environment and another for a Production Environment.
  3. In the Environment section, click the radio button of the environment (Production or Sandbox) the Target URL is associated with.
  4. See What is the difference between Sandbox and Production environments? for more information.
  5. See the Configure Advanced Options section.

D. Configure Advanced Options

By default, the REST protocol is selected for your API, a Default Profile (Any in and out), and Default Operation are specified. After specifying the Target URL and Environment, you can optionally update the existing protocol (REST), or change the protocol to SOAP in the Advanced Options section.

Configure Protocol:

  1. On the Advanced Options line click Show to expand the section.
To configure a SOAP API:
  1. Click the SOAP radio button. You can enter a WSDL URL directly or upload a zip archive:
    • WSDL URL—Click the WSDL URL radio button, enter the WSDL URL and click Get. The operations load into the Operations section.
    • Zip Archive—Click the Zip Archive radio button, then click Browse and select your zip archive. Click Upload. The Upload File dialog displays Select a WSDL File from the Archive and presents a listing of WSDL files that can be selected. Click the radio button of the WSDL file you would like to upload. Click Select. The operations load into the Operations section.
To configure a REST-based API:
  1. Click the REST radio button and select a Default Profile from the drop-down menu. Any in and out is the default selection.
  2. A "Default_Operation" is automatically assigned, with a GET method, Path that is pre-filled with the default URI, and "API Default" selected for the Request and Response serialization.
  3. Modify the "Default_Operation" and/or click +Add and specify the operations for the API definition based on your requirements.

    For the typical REST service, the most common methods, URIs, and serialization types would be:

    Operation Method URI Request (Input) Response (Output)
    list GET / N/A text/xml
    read GET /{id} N/A text/xml
    add POST / text/xml text/xml
    delete DELETE /{id} N/A text/xml
    update PUT /{id} text/xml text/xml

  4. Click the Add Content-Length checkbox if you would like to send the Content_Length heading to the Target API. This disabled chunked encoding.
  5. Click the Use HTTP 1.0 checkbox if you need to force the HTTP version to 1.0 for the Target API. It is unlikely to be needed.
  6. See How do I add a REST service? for a sample walkthrough.

E. Configure Proxy

  1. After specifying the Target information, click Next to continue. The Proxy page displays. Here you will specify the Published URL that represents what users will select when accessing your API. The page displays a summary list of all Production and Sandbox endpoints specified in the previous step. It's recommended that you use a Proxy API to take advantage of important platform functionality. See What is a Proxy API? for more information.

    Note: As a security measure, users will be able to access a proxy that will run in the Cloud, and access the API implementation directly.
  2. The Advanced Options section displays the settings configured in the Target section. If you would like the Proxy configuration to be different than you initially specified in the Target section, you can update the existing settings.

    For example, you might have two APIs that have the same Target information, but different Proxy information. Alternatively, you might have a SOAP API implementation but want to offer developers a REST API implementation, in this case, the Target would be SOAP, and the Proxy would be REST.

F. Enable / Disable Proxy API

  1. In the Proxy API section, click a radio button to indicate whether you would like to proxy your API.
    • If you select No, click Save to complete the API configuration process.
    • If you select Yes, proceed and configure the Production Endpoint and Advanced Options.

G. Configure Production Endpoint

  1. In the Production Endpoint section, configure the proxy information for each Sandbox or Production endpoint.
    • In the URL section, specify the protocol. When the system proxies the API, the URL is made up of a selected protocol and hostname in the first field plus the path in the second field. You do not need to specify a path.
    • For Allow Anonymous Access, click the Yes or No radio button to indicate whether you would like to enable or disable anonymous access for this API. See What is Anonymous API Access? for more information.
    • For This API requires Approval, indicate whether you would like to approve API access requests made with the API Access Wizard. All API Access Requests can be monitored by API Providers and designated administrators in the API Name > Apps section.
    • If you select Yes, proceed and configure the Production Endpoint and Advanced Options.
    • Its common practice for Sandbox endpoint requests to be auto-approved. Production endpoint requests usually go through an approval cycle as API developers may want to review the app requesting access to see how the API functionality is being used.
  2. Enter the CNAME. This represents the host name that is assigned to the proxy that is visible to individuals viewing your API. Note: The API Provider is responsible for mapping the Host Name of the IP Address to the applicable DNS.
    • As you populate the fields, the Published URL display name updates to reflect your changes.

H. Configure Advanced Options

  1. On the Advanced Options line click Show to expand the section.
  2. The Advanced Options section allows you to select a protocol for the Proxy API, select policies, and select a Default Profile (REST option only). It displays the settings configured in the Target section.
  3. If you would like the Proxy configuration to be different than you initially specified in the Target section, you can update the existing settings. For example, you might have two APIs that have the same Target information, but different Proxy information. Alternatively, you might have a SOAP API implementation but want to offer developers a REST API implementation, in this case, the Target would be SOAP, and the Proxy would be REST.

    If the path in the proxy is different from that in the target, it is shown as "Path not synced with target." If the Proxy configuration is different by design (as noted in the explanation above), do not resync. If you intend for the Proxy information to match the Target, go to the Target definition and click Sync to Proxy.

    Note: If you need to add new operations, add them on the Target page first, then continue your configuration on the Proxy page.
Select Default Profile:

  1. Select a Default Profile from the drop-down list box. See What is an API Type Profile? for more information.
Configure Method, Path, and Content Type for Operations:
  1. Select a Method from the dropdown menu, specify a URL in the text box, and configure a Content Type for the Request and Response message of each operation.
  2. See What are the supported Methods and Content Types for Requests? for more information.
Select Policies:
  1. In the Policies section, select the policies that you would like the system to enforce on the proxy. Note: You MUST select one security policy (e.g., Category: Simple Header Security) and you should select a monitoring policy if you want to see charts and logs. If no policies display, consult your API Provider or Site Administrator. See What security and monitoring policies are supported?
  2. Also note that if you select a monitoring policy, app data is not supported in My APIs > Monitoring if Anonymous API Access is enabled. See What is Anonymous API Access? for more information.
  3. If your API will be supporting OAuth, its best practice to use the Edit function on the API Details page to select the OAuthSecurity policy after you have configured the API to support OAuth (i.e., adding an OAuth Provider in the Site Admin > Domains section), and configuring the API using the OAuth Details function on the API Details page.
  4. After making your changes click Save. Your API is now registered.
  5. If you will be configuring your API with OAuth, review the information in the OAuth Support section to determine next steps.

Back to top

How do I add an API from an existing API Gateway service (API with Existing Service)?

If you already have an API that's set up as a service in the API Gateway, or you want to create the service using the flexible service definition model offered by the API Gateway, you can use the Add API with Existing Service function to add the API to the platform.

The platform references the information already set up in the API Gateway so you don't have to set up all the API details again.

You might choose this option over the "Add API with New Service" option if your service matches any of the following descriptions:

To add an API from an existing API Gateway service:
  1. From the Plus Menu, select Add a New API. The Select Type of API overlay appears.
  2. Choose API with Existing Service and click Add. The Add API with Service wizard displays at the first page, the Details page.
  3. Specify basic API details: Name, Description, Visibility, Version ID, and Version Description.
  4. Check the box to indicate whether the API uses licenses.
    For more information about setting up an API to use licenses, see How do I determine what licenses will be available for my API? For general information about the Licenses feature, see Licenses: Feature Overview.
  5. Optional: set up an avatar for your API. Click Upload and navigate to the file.
  6. Click Next to go to the Target API page.
  7. Set up the following values for at least one environment in which the API is running:
    • Service Key. Enter the environment name, unique service key, or URL. The platform locates the API Gateway service, and you can then select it.
      To locate the appropriate value, go to the API Gateway, open up the service, and click Edit. Copy the value and paste it into this field.
    • Allow anonymous access (yes/no)
    • Approval required (yes/no)
  8. Click Finish.

Back to top

What is scope mapping and how do I set it up?

If your API is using the Licenses feature, scope mapping is the key to defining which portions of your API will be available for which licenses. The scopes and licenses themselves are defined by the Business Admin, but at the API level you determine which operations are assigned to which scopes. This in turn determines which licenses will be available to app developers requesting access to your API.

For example, let's say your API includes a set of operations relating to calendar functionality and another set of operations relating to email access and management. App A might only need access to the calendar functionality, and App B might include an email client and might require access to the operations relating to email. The scope mapping feature enables you to group individual operations into logical groups that can be separately packaged into a license for App A and another for App B.

As another example, let's say you want to offer access to your GET operations, and a higher level of access, for a fee, to all operations including add, modify, and delete. The Business Admin defines READ and MODIFY scopes, and then assigns each to a separate license. The API Admin assigns GET operations to the READ scope and assigns all operations to the MODIFY scope. Users who choose the paid license get access to all scopes; users who choose the free license can only access the GET operations.

At runtime, when a request is received to an API proxy from a particular app, the request is only passed through to the API if it is using one of the specific operations covered by the license governing the app/API contract.

To perform scope mapping:
  1. First, make sure the Licenses feature is enabled in the API. From the API Details page, click Edit, and make sure the Use Licenses checkbox is checked.
  2. From the API Details page, click Scope Mapping. The Edit API Scope page displays.
  3. Choose a scope mapping approach:
    • API-wide Mapping: choose this if you're not subdividing your operations for licensing purposes.
    • Operation-specific Mapping: choose this if you'll want to grant access to some portions of your API separately.
  4. Operation-specific mapping only: For each operation, in the Scope column, click Select. The Select Scope popup displays. Choose one or more scopes for the operation and click Confirm.
  5. Repeat for each operation.
  6. Click Save.

Back to top

How do I inform app developers about available licenses and API access?

As a standard practice, a list of available Licenses and the level of App Access provided by each License should be included in the documentation for your API.

Back to top

How do I add a REST service?

The following example illustrates how to add a REST service from the BingVirtualEarth API.

Pre-conditions

  1. A working REST service.

A. Add REST Service

  1. From the Plus menu, select Add a New API. The Add API Wizard displays.
  2. Review the tooltips for each option to gather additional details and recommendations.
  3. On the API page, specify the information as illustrated below, and click Next to continue.

  4. Configure the following information:
    • On the Target page, add the "Target URL" for the REST service.
    • Expand Advanced Options and select the REST radio button.
    • Add an Operation with the GET method, click SYNC TO PROXY, and click Next to continue.

  5. Configure the following information:
    • On the Proxy page, enter the URL and CNAME of the Production Endpoint.
    • For Allow Anonymous Access, click the No radio button. See What is Anonymous API Access? for more information.
    • For This API requires Approval, indicate whether you would like to approve API access requests made with the API Access Wizard. All API Access Requests can be monitored by API Providers and designated administrators in the API Name > Apps section.
    • Expand Advanced Options and verify the settings are correct (i.e., they match the Target section in the previous step).
    • In the Policies section, select the policies that you would like the system to enforce on the proxy. Note: You MUST select one security policy (e.g., Category: Simple Header Security) and you should select a monitoring policy if you want to see charts and logs. If no policies display, consult your API Provider or Site Administrator. See What security and monitoring policies are supported?
    • Click Save.

B. Set up Contract

  1. Add a new app. See How do I create a new app?
  2. Request API access for the newly added REST API. See How do I add APIs to my app?
  3. The API Administrator will then approve and activate your API Access Request. After approval, you are ready to test the API with your app.

C. Test API

You can test the API with the Dev Console or with the REST clients mentioned in the Pre-conditions section above.

The request URL should be the added API URL with the same parameters for the physical service. For example:

http://<API_URL>/<API_path>?postalCode=90020&o=xml&key=AoCDRhKKY0Gy6hlx1Ncl1PwiV7GqoGU_MebxLQvmhxy_bsAtzVfmVtzFsjOYSCTZ

Back to top

How do I manage API visibility?

When you create an API using the Create a New API function you can control whether visibility of the API is Public or Private via the "Visibility" option. You can change API visibility based on your requirements by using the Edit function on the API Details page.

Back to top

What is a proxy API?

The Add a New API function includes a proxy API option that allows you to configure an endpoint in a particular environment (e.g., internal or external network) that is accessible by your target applications.

A proxy API endpoint exists in the Cloud and is similar to a virtual service. As a security measure, users will be able to access a proxy that will run in the Cloud, and will not be accessing the API implementation directly.

Based on the development cycle of your API, you can chose to expose selected functionality in your API by defining a Proxy API for each endpoint and selecting which functionality (e.g., operations) you would like to expose. This approach allows you to manage the API lifecycle and expose functionality based on your requirements (e.g., development phase, testing, production, etc.).

Advantages:

Internal / External Networks—If you would like to access to your real API on an internal network, but would like to expose specific functionality on an external network, you can add the API Target URL using the Add a New API function, and then virtualize the API by specifying a Proxy API Target URL for specific functionality you would like to make available on an external network.

Bridge Between App and Proxy API—If your API is focused on the business aspects of the API or service, you can set up the proxy API to provide other tasks such as security enforcement or specifications required by the target (e.g., API specs for the app team, etc.).

Sandbox / Production Endpoint Access—Adding a Proxy API allows app developers to gain access to your API sandbox endpoint (to test API functionality in their app), and production endpoint (to use API functionality in a live application).

Contract Enforcement—If you configure your API with a proxy, you can take advantage of the platform's contract enforcement functionality. Here's how it works:

Service-Level Policies —If you configure your API with a proxy, you can take advantage of the service level and quota management policy functionality to monitor your API to ensure it meets the defined standards of service level performance contracts.

Example Scenarios:

Scenario 1—You build an API and would like to expose specific functionality for the purposes of collaborating with a selected development and/or discussion group. You do not want to the API to be visible to anyone outside the selected group. To accomplish this:

Scenario 2—You build an API and would like to expose specific functionality to the public for them to use in their applications. To accomplish this:

Back to top

What is the difference between sandbox and production environments?

Back to top

What is an API Type Profile?

An "API Type Profile" is used for proxy APIs to identify the type of content an API will accept from the consumer (IN), and will be returned by the API to the consumer (OUT). IN and OUT identifiers are combined with content types (i.e., ANY, JSON, FORM, and XML) and are packaged on the API Type Profile drop-down menu in profile sets. The following content types are supported:

Content Type Description
ANY Indicates that the content is not part of the API definition. Refer to the API documentation for an explanation.
JSON Indicates that JSON will be expected. Refer to the JSON specification for more information (http://www.w3.org/TR/rdf-sparql-json-res/#mediaType).
FORM Indicates that form encoding will be expected. Refer to the form- urlencoded Media Type specification for more information (http://www.w3.org/MarkUp/html-spec/html-spec_8.html).
XML Indicates that XML will be expected. Refer to the XML specification for more information (http://www.w3.org/TR/REC-xml/).

Back to top

What are the supported HTTP method types and content types for requests?

If you chose to proxy your API, you can optionally configure the operations with Methods, URLs, and Content Types. After the API settings are saved, the specified information is synched with the Target URLs. The following options are supported:

Option Name Description
Method The "Method" is a dropdown menu that allows you to map to the HTTP method that must be used at runtime when formulating an HTTP request message. Options include ANY, GET, PUT, POST, and DELETE.
Path The "Path" is a text field that allows you to specify a location attribute that can be used to map portions of an HTTP request URI to portions of a WSDL input message. The specified syntax must match the inbound URI pattern. For example, if the HTTP URL looks similar to http://endpoint/context/quotes/xyz where xyz is a variable, then the URI syntax would be /quotes/{var}. The URI can contain multiple variables denoted by {}. This field is optional.
Content Types The Request and Response sections (accessible by clicking Show for each operation), includes a list of "Pre-defined" content types that support different message processing requirements for Input and Output messages.

Request Content-Type—This option is used to describe the content type of the Request Message. The platform uses input serialization to correctly set the content type of the request being issued. The "Pre-defined" content types include API Default, Any, application/x-www-form-urlencoded, text/xml, application/xml, and application/json.

1) If the request message is a GET or DELETE, the query string contains items that are appended to the resulting XML or JSON message.

2) If the request message is a PUT or POST, the body contains a URL encoded string whose elements are appended to the resulting XML or JSON message. A value of an XML-based content type assumes that the body contains the whole XML message.

Response Content-Type—This option is used to describe the content type of the response message when it is not a fault. The platform uses output serialization to correctly set the content type of the response sent back to the consumer when the response is not a fault. The "Pre-defined" content types include API Default, Any, text/xml, application/xml, application/json.

NOTE: If Proxy API = Yes, the selected content types are automatically synched to the specified proxy address. If you do not want the content type selections synched to the proxy address, click delete next to the "sync to proxy" icon.

Back to top

What is anonymous API access?

The Add API Wizard includes an Allow Anonymous Access option on the Proxy page that allows you to enable or disable anonymous access to Sandbox and Production endpoints.

Allowing anonymous access to an API endpoint in the Sandbox environment is useful if you would like to offer a preview of an API to developers without requiring users to create an app or sign up to the platform. For example, if you have a specific feature set you would like to expose as part of promoting your API, you can expose those operations in your API configuration, and enable the Proxy API and the Allow Anonymous Access option.

Developers can read the documentation and access the API without signing up and requesting access to the API. If a developer tries out the API and likes it, he/she can then sign up to the platform, create an app using the Add a New App function, and submit an API Access Request.

Note: Anonymous access is typically granted to API Sandbox endpoints, but it is generally not a standard practice to grant anonymous access to Production endpoints.

When you enable anonymous access in the Add a New API Wizard by selecting Yes to Allow Anonymous Access on the Proxy page, the This API Requires Approval option is disabled. This means that app developers are not required to submit an API Access Request to access the API, except in the following scenarios:

API Charts / Logs with Anonymous API Access:

Back to top

How do I add an API version?

When you add a new API, the "Version ID" that you specify in the Add a New API Wizard represents the version number that will display on the Version drop-down menu. You add a new API version using the +Version function on the API Details page. Adding an API version follows the exact same process as adding your first API except that the information from the current API version is replicated. From here you can edit/customize the API definition based on your requirements.

To add an API version:
  1. Click the My APIs quick filter in the top navigation. The APIs Summary page displays.
  2. Click the name of an API you would like to create a new version of. The API Details page displays.
  3. From the Version drop-down menu, select the API version that will serve as the base content for the new API version.
  4. Click + Version. The Add API Version screen displays and presents a duplicate copy of the current API version.
  5. Change the Version ID, Tags, Visibility option, API Description, and Version Description.

    Note that the API Name is cannot be modified for an API Version. You can only change the API Name using the Edit function on the original API.
  6. Update the API contents based on your requirements. See How do I add a new API (API with New Service)? or How do I add and set up an API? for details on configuring your API.
  7. After you have defined your API version, click Save. The API is saved and the Version ID specified displays in the Version drop-down menu.

Back to top

How do I edit an API?

The platform includes two options for adding an API, accessed via the Add a New API function on the Plus Menu (the + icon at the top of the page); Add a New API and Add API with Service. The steps for editing an existing API vary according to the way the API was originally created.

You can modify your API definition using the Edit function on the API Details page.

To edit an API:
  1. Click the My APIs quick filter in the top navigation. The APIs Summary page displays.
  2. Click the name of the API you want to edit. The API Details page displays.
  3. From the Version drop-down menu, select the API version you want to edit.
  4. Click Edit. The Edit API Info wizard opens, showing the current API information. If the API was created on the platform, the wizard has three pages; API, Target, and Proxy. If the API was created with an existing service, the wizard has only two pages; Details and Target API.
  5. Update the API contents based on your requirements. For details on the values for the API, refer to the applicable topic for adding the API; How do I add a new API (API with New Service)? or How do I add an API from an existing API Gateway service (API with Existing Service)?
  6. Click Save.

Back to top

How do I export an API?

You can export information about an API to an external file. You can then import that file to another instance of the platform. One use of this feature is to move data from one environment to another, such as from a development environment to a testing or production environment.

You can also choose whether or not to export additional data associated with the API, such as policies, contracts, scopes, and documentation.

To export an API:
  1. Log in as the API Administrator.
  2. Select My APIs > API Name. The API Details page displays.
  3. Click Export.
  4. In the Export overlay, choose the versions you want to export and the options. If you want to export all information about the API, check all boxes. You can export the following data associated with the API:
    • Operational Policies
    • QoS Policies
    • API PKI
    • API Administrators
    • Scopes
    • API Contracts
    • Resources/Documentation
  5. Click Export.
  6. Choose to save or open the export file.

Back to top

What are the contents of the API export file?

The API export file includes all the core information about the API, as well as any of the optional additional information you specified.

The file has a very specific structure. It will look something like the image below:

File structure for an API export file

The export file will generally include the following:

Back to top

How do I import an API from an export file?

Once you've exported an API to an external zip file, it can be imported to another environment. For example, you can export from a development environment and then import to a testing or production environment.

The Business Admin can export information about an API to an external file. However, only a Site Admin or Business Admin can import.

If you need help with import functions, contact your Administrator.

If you are an Administrator, refer to How do I import site, app, or API information from an export file? for instructions.

How do I delete an API?

To delete an API:
  1. Click the My APIs quick filter in the top navigation. The APIs Summary page displays.
  2. Click the name of an API you would like to delete. The API Details page displays.
  3. Click - Version. The confirmation message "Do you really want to delete this API?" displays. Click OK. Your API is deleted.
  4. If your API is the last API version available, you'll be prompted to confirm that you want to delete the last version, which deletes the API. Click OK to confirm.

Back to top

How do I determine what licenses will be available for my API?

There are a couple of steps you'll need to complete in your API setup to define the licenses that app developers will see when requesting access to your API:

  1. In your API setup, make sure that the Use Licenses box is checked. Go to the API Details page, click Edit, and verify that the box is checked.
  2. Do scope mapping. From the API Details page, click Scope Mapping. For instructions, see To perform scope mapping.

The scopes are the link between your API and the licenses that are offered to app developers. If you have any questions regarding which scopes to assign or which licenses will be available, consult your Business Admin.

For an overview of the Licenses feature and the relationship between the setup steps performed by the Business Admin and those done by the API Admin, and the relationship between scopes and licenses, see Licenses: Feature Overview.

Back to top

How do I edit the license on an API access request?

An API Administrator can change the license for a specific API Access Request prior to approving the request.

If you want to review the license scope of API access requests before approving, make sure you've selected the This API requires approval option in the API setup (API > Edit > Proxy page). If the API is set to auto-approve requests, you won't have the opportunity to modify the license.

To edit the license scope for a pending API access request:
  1. Go to APIs > Apps.
  2. Select the API Access Request you want to modify. It must have a status of Access Pending.
  3. Click Edit. The API Access Wizard launches and loads the Licenses page.
  4. Change the license option as needed.
  5. Click through the rest of the wizard and then click Save.

Back to top

How do I see the status of my API's contracts with apps?

You can review the status of your API's connections, including pending and active API access requests, in the My APIs > API > Apps page. This page provides a high level summary of workflow status for apps with current API access contracts or pending API access requests for the current API.

Each listing includes:

The following table shows App Status and App Management Tasks for app/API contracts:

Contract Status Description
Access Requested An App has requested access to an API but the request has not been approved and activated in the Sandbox or Production environment.
Active API Access has been approved and activated.
Inactive API access has not yet been requested.
Rejected The API Access Request has been rejected.
Suspended API Access that was previously active has been suspended.

 

App Management Task Description
Cancel Cancels an API Access Request. Listing is removed from the API Connections page. Requestor must submit another request to initiate the process again.
Suspend Suspends the API Access Request. This action can only be performed when the request status is Active.
Resume Resumes the API Access Request and changes the request status to Active after it has been suspended.
Switch to Sandbox Switches the app to the Sandbox Environment and uses the Sandbox Endpoint.
Switch to Production Switches the app to the Production Environment and uses the Production Endpoint.

 

API Access Request Task Description
Approve Approves the API Action Request.
Note that the request still requires activation after it has been approved.
Reject Rejects the API Action Request.
Cancel Cancels the API Action Request. Requestor must submit another request to initiate the process again.
Activate Activates the API Access Request.
Suspend Suspends the API Access Request and is performed after the request has been activated.
Resume Resumes the API Access Request and puts it into an activated state after it has been suspended.

Back to top