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

API Setup

  1. What are APIs?
  2. What are the recommended API development best practices?
  3. What is the minimum requirement for adding an API?
  4. What security and monitoring policies are supported?
  5. What is the minimum policy requirement for my API?
  6. How do I add an API?
  7. How do I add a new API (API with New Service)?
  8. How do I add an API from an existing API Gateway service (API with Existing Service)?
  9. How do I add a REST service?
  10. What is Anonymous API access?
  11. What is a private API?
  12. How do I manage API visibility?
  13. What is a proxy API?
  14. What is the difference between sandbox and production environments?
  15. What is an API Type Profile?
  16. What are the supported HTTP methods and content types for requests?
  17. What is a Default Profile for a REST API?
  18. How do I define a custom content-type for a REST API?
  19. What is auto-connect?
  20. How do I set up auto-connect for my API?
  21. How do I set up my API to support CORS?
  22. How do I set up my API to allow anonymous access?

API Management

  1. How do I add an API version?
  2. How do I edit an API?
  3. How do I export an API?
  4. What are the contents of the API export file?
  5. How do I import an API from an export file?
  6. How do I delete an API?

Scopes and Licenses

  1. How do I determine what licenses will be available for my API?
  2. How do I edit the license on an API access request?
  3. What is scope mapping and how do I set it up?
  4. How do I inform app developers about available licenses and API access?
  5. I want to exclude an operation so app developers can't use it. How do I do that?

API Setup

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 (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 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 (developers writing apps) 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)
CORSAllowAll

CORS (cross-origin resource sharing) enables users to access resources from within the browser serving a web page, and defines a way in which the browser and the server can interact to determine whether or not to allow the cross-origin request.

The CORSAllowAll policy allows all cross-origin requests.

If you are using the platform as a proxy, you can add the CORSAllowAll policy to allow cross-origin requests to the proxy service.
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 developer 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.

For more information about policies, see Policy List.

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 (for example, Category: Simple Header Security). If you want to see charts and logs, you must also select a monitoring policy.

If there are no policies available for selection, consult your Site Admin.

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.

Once the basic API setup is done, there are several other important steps you might need to complete, depending on the nature of your API:

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, API Description, Version Description, and API Icon. This information is displayed on your public API page and 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, 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. 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. For more information about the default profile, see What is a Default Profile for a REST API? below.
  2. A placeholder value, Default_Operation, is available for you to define the first operation. Modify it as needed, specifying these values:
    • Method (HTTP verb)
    • Path
    • Operation Name
    • Settings
  3. To add another operation, click +Add and specify the values as needed. Specify content-type for the request and response if they are not the same as the default profile. To define a custom content-type, see How do I define a custom content-type for a REST API?

    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 header to the Target API. This disables 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.

E. Configure Proxy

  1. After specifying the Target information, click Next. 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 (Proxy)

  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. The default URL shown in this field is constructed from the deployment zones loaded in the platform or, if no deployment zones were loaded, based on Network Director instances configured in the organization path from the root to the tenant organization.
    • 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. The API Provider is responsible for mapping the Host Name of the IP Address to the applicable DNS.

    Note: There are some headers that need to be set up in the underlying infrastructure, if your implementation uses load balancing, so that messages will be passed correctly. This is a Site Admin task. Full information is in the Site Admin help (How do I set up and configure an OAuth Provider domain?).

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 (for example, 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. Tip: to select multiple policies, hold down the Ctrl key while selecting subsequent policies. To de-select a policy that was already selected, hold down Ctrl and click the policy again.
  3. 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.
  4. If your API will be supporting OAuth, it's best 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.
  5. After making your changes click Save. Your API is now registered.
  6. 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. A wizard opens and displays at the first page, Details.
  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

How do I add a REST service?

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

Pre-conditions

Before you start, to work through the example below, you must have:

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 then click Next.

  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 then click Next.

  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 (for example, 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 get API access for 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 built-in Test Client tool 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

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

What is a private API?

A private API is one that has a visibility setting such that it is 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

How do I manage API visibility?

When you create an API using the Create a New API function you can control visibility of the API. 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?

When you set up your API on the platform, using the platform as a proxy, your API is the Target API and the platform is the Proxy API. This allows you to configure an endpoint in a particular environment (for example, 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 access the proxy that runs in the Cloud, rather than accessing the API implementation directly. Traffic is channeled via the proxy to your target API.

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 (for example, operations) you would like to expose. This approach allows you to manage the API lifecycle and expose functionality based on your requirements (for example, 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 (for example, API specs for the app team).

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 synchronized 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" media 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" media types include API Default, Any, text/xml, application/xml, application/json.

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

Back to top

What is a Default Profile for a REST API?

When you're defining a REST API in the platform, the basic API definition includes a default profile. This determines the content-type for request and response that will be used if you don't specific anything different. It's just a default for timesaving purposes. For example, if 80% of your operations send and receive JSON content, you can choose JSON in and out. The default is Any in and out.

Once you've specified the most common scenario as the default profile, you can go ahead and specify content-type for any operations that have different values, by selecting from the list of available content-types. To view the list, click the Show link at the far right of the Default_Operation line, in the Settings column.

You can also specify a custom content-type. See How do I define a custom content-type for a REST API? below.

Back to top

How do I define a custom content-type for a REST API?

When you're adding or editing the API definition for a REST API, you have three choices with regard to defining the content-type for request and response messages:

To specify a custom content-type:
  1. Follow the instructions in To configure a REST-based API until you get to Step 3.
  2. In the Settings column at the far right of the line for the operation, click the Show link. You will see the list of media types available for both request and response.
  3. In the Request column, clear the API Default box, and then click Custom. A new field appears for you to define the custom content-type.
  4. Specify the value. Make sure it's a valid media type with correct syntax.
  5. Continue setting up your API, specifying a custom media type for other operations as needed, and then click Next to go to the Proxy page.
  6. Follow the steps in Configure Proxy above.

Back to top

What is auto-connect?

The platform's auto-connect feature allows an API Admin to set up the API so that when a new app is created on the platform, a contract with the API is created automatically. The API Admin specifies the details of the access granted with the auto-connect feature, such as whether access is to the sandbox or production environment, or whether access is limited to specific operations or a specific transaction volume (via the Licenses feature, implemented with scope mapping).

You can change the auto-connect details for your API at a later time; however, be aware that if contracts have already been created, those will continue unless you specifically end them.

If your API uses licenses, it's important to set up scope mapping for your API before setting up the auto-connect feature, since the auto-connect settings reference the scope mapping settings.

For instructions on setting up auto-connect for your API, see How do I set up Auto-Connect for my API? below.

Back to top

How do I set up auto-connect for my API?

If you want to grant new apps automatic access to your API, you'll want to set up the auto-connect feature.

Note: If your API is using licenses, set up scope mapping first. Then, follow the instructions below.

To set up auto-connect for an API:
  1. Go to the Details page for the API.
  2. Click the Auto-Connect button.
  3. In the Set Up Auto-Connect Settings page, check one or more boxes to indicate environment for auto-connect contracts: Production, Sandbox, or both.
  4. Conditional: if your API uses the Licenses feature, a list of scopes is displayed for any environment you selected. Check one or more scopes that you want to allow for an auto-connect contract, for each environment selected.
  5. Click Finish.

Back to top

How do I set up my API to support CORS?

If you want your API to support cross-origin resource sharing (CORS), you can do that in your API implementation in the platform.

In your API setup, add the CorsAllowAll policy to the proxy API implementation (API > Details > Edit > CorsAllowAll policy). When the API definition includes this policy, the proxy endpoint will accept request messages that come from a different domain, in the context of a browser.

Back to top

How do I set up my API to allow anonymous access?

The platform supports app developers testing an API without choosing a specific app (anonymous context).

In order for developers to be able to test your API in this way, you must have some settings in place:

Back to top

API Management

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 Admin.
  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 (Current or All) 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:
    • Export Operational Policies
    • Export QoS Policies
    • Export API Administrators
      Note: the relationship of the user as an API admin is exported, but the user is not exported. The user must exist in the target environment. If the user does not exist when the information is imported, the API is created without that admin. From there, either a) the user can sign up and be invited to be an admin, b) the user can sign up and the API data can be reimported, c) another individual can be designated as an API admin.
    • Export API Implementation Services
      Note: If the API was created using an existing service (see How do I add an API from an existing API Gateway service (API with Existing Service)?), this option allows you to choose whether or not to export the API implementation services, as set up in Policy Manager. If the API was created as a new service (see How do I add a new API (API with New Service)?), implementation services are always exported along with API.
    • Export API Contracts
    • Export Scopes
    • Export Resources/Documentation
    • Export API PKI
  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

Scopes and Licenses

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

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 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. If you assign scopes to an operation, all apps with licenses that include one of those scopes can use the operation. If no scopes are defined for an operation, it means that no scopes are needed for that operation (the least secure scenario).
  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

I want to exclude an operation so app developers can't use it. How do I do that?

You might have one or more operations that are part of your API but you don't want to make them available for app developers. Perhaps they are still under development or being tested.

If you want to make sure no app can access these operations, the best way to do it is with scopes and licenses. You can use a scope that isn't assigned to any license, and use the API scope mapping wizard to assign that scope to the operation. When you're ready to share the operation, you can update the scope assignments, assigning a scope that's assigned to a license so that app developers can choose to access it.

Back to top