Quick Start (API Provider)

How do I add and set up an API?

The API setup process involves adding an API to the platform, uploading API documentation, uploading and activating legal agreements, and assigning API administrators. After you have completed the API setup process, you can then test the API by assuming the role of an App Developer by creating an app and requesting access to the API using the API Access Wizard.

The following quick start provides a complete walkthrough of the API setup process and provides jump off points to more detailed documentation for each of the steps.

To register an API you must complete the following activities:

• Define API: Add the API description, Target URL, and Proxy URL (if applicable) to the platform using the Add a New API Wizard.
• Upload API Legal Agreements: Develop, upload, and activate legal agreements that will become a part of the API Access Wizard and can also be viewed in the API > Legal section.
• Upload API Documentation: Add API documentation that users can view in the API > Documents section.
• Select API Administrators: Send invitations to individuals you would like to have API maintenance privileges.
• Invite Users to Private API: Create an API Group and send out invitations to individuals you would like to be group members.

Step 1: Add New API

A. Launch the Add a New API Wizard

The first step in the process is to add an API. To do this:

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.

B. Specify API Information

1. On the APIs page, specify the API Name, Version ID, Tags, Visibility (Public/Private), API Description, Version Description, and API Icon for the API. All information here displays on your customer-facing API Details page.
   • See How do I manage API visibility? for information on Public and Private APIs.
   • See How do I upload and crop icons? for details on configuring your API Icon.

C. Specify Target URL and Environment

1. After specifying the API information, click Next to continue. The Target page displays. Here you will specify the Target URL, select the Environment, and configure Advanced Options for your API.
2. In the Target section, specify the Target URL (i.e., endpoint) of the API implementation. If you would like to specify additional Target URLs, click +Add. For example, you might add one URL for Sandbox Environment and one for 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. Continue to 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 SOAP:

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 REST:

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 will not be accessing 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 the applicable 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.
   • It's 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 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 change.

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), and 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., 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?

   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.

   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.

2. After making your changes, click Save. Your API is now registered.

Step 2: Create Legal Agreements

If you will require users of your API to accept any type of end user license agreement or developer agreement, you must create and upload the legal agreement content. The adding legal agreements step should be performed after you add an API using the Add a New API Wizard so the legal agreements will be available for review and acceptance when an App Developer requests access to the API using the API Access Wizard.

All legal agreements must be written and maintained outside of the platform using your own HTML editor. Review the following key topics in the Content Development Guidelines section to get started. When you are ready to publish your legal agreements to the site, proceed to Step 3: Upload Legal Agreements.

• Who can edit API and legal agreement content?
• How do I edit HTML page content?
• What style sheets do I use for my legal agreements?
• How do I organize my API and legal agreement documentation files?

Step 3: Upload Legal Agreements

You can upload completed legal agreements via the File Explorer.

Here are some points to consider:

• You can upload one or more legal agreements for an API based on your requirements.
• Each time you upload a new legal agreement, it initially has a Draft status.
• When you activate the legal agreement, you assign a name and description for the legal agreement.
• After the activation is complete a hyperlink is added to the Legal page that you can click to view each legal agreement.
• You can view each legal agreement by clicking the hyperlink.
• To modify the display text for the hyperlink, use the Edit function on the Agreements Summary page.
• See How do I upload my legal agreements? in the Content Development Guidelines for information on how to upload your legal agreements.
• Refer to the Legal Agreements section for information on how to manage legal agreement content.

Step 4: Activate Legal Agreements

When legal agreements are initially uploaded, they are in Draft mode and not visible on the site. To make them visible on the site and available in the API Access Wizard, you must activate them. To do this, click the Activate button; assign a name and description to the legal agreement, and save the configuration. An activated legal agreement displays in the API Access Wizard where an API user can review and accept it as part of the API access approval process.

To activate a legal agreement:

1. Navigate to API > API Name > Legal.
2. Click Manage Agreements.
3. Chose the legal agreement you want to activate. In the Status column, click Activate. The Edit pop-up displays.
4. Specify a Name and Description for your legal agreement. Click Save to commit your changes. After you initially assign a Name and Description to a legal agreement, you can update it using the Edit function.
5. Your legal agreement is activated and the Deactivate button displays. The legal agreement will now be available in the API Access Wizard.
6. To test the legal agreement and verify that it displays correctly in the API Access Wizard, create an app and access an API to view the legal agreement. See How do I create a new app? and How do I add APIs to my app?

Step 5: Create API Documentation

Each API should offer API documentation. All API documentation must be written and maintained outside of the platform using your own HTML editor. Review the following topics in the Content Guidelines section. When you are ready to upload your API documentation to the site, proceed to Step 6: Upload API Documentation.

• What API documentation options does the platform provide?
• What is Swagger and how does it work?
• What are the Swagger controls and how do I edit page content?
• Who can edit API and legal agreement content?
• How do I edit HTML page content?
• What style sheets do I use for my HTML API documentation?
• What document styles can I use?
• Can I add other types of content?
• How do I organize my API and legal agreement documentation files?

Step 6: Upload API Documentation

You can upload API documentation using the File Explorer. Review the following guidelines:

• How do I zip my documentation files?
• How do I upload my API documentation?
• Can I upload existing API documentation and use it in the platform?

Step 7: Invite API Administrators

Maintenance of an API can be performed by the API Developer who initially added the API to the platform, or individuals who accept invitations to be administrators. To send an invitation to an individual you would like to have API administrator privileges:

1. Navigate to My APIs > API Name > Admins. The Admins page displays.
2. Click Invite More. The Invite Administrators page displays.
3. In the Email text box, enter the email address of individuals you would like to invite to your development team. Separate multiple email addresses with commas.
4. In the Add a Brief Message text box, specify the invitation text you would like to send to your invitees.
5. After completing your entries, click Invite. The invitation email is sent to the invitee.
6. After the email invitation is sent, the platform will post an administrator invitation to the platform member's Dashboard. The invited platform member can then log in to accept or decline the administrator invitation.
7. Refer to the Admin Management section for a complete list of admin management topics.

Note: When you create an API, you are the administrator. Your administrator privilege is automatically approved and is posted to the Admins Summary page. You can then invite additional administrators using the Invite More function. Invitees that are not members must sign up before accepting the team invitation.

Step 8: Create Private API Groups (for APIs configured with Visibility = Private)

If you API is configured with Visibility = Private, you can use the Private API Group Access functionality which provides a method of creating common interest groups around specific APIs. Group accounts are created by API Administrators, and member invitations are sent and managed by the API Administrator. Only API Administrators can create Private API Groups.

Refer to the Private API Groups section for complete instructions on creating a Private API Group, sending out invitations, and assigning group leaders.

Step 9: Test Your API

You can test your API by creating an app, requesting API access to your API, and configuring the app to consume your API. See How do I create a new app and configure it to consume APIs? for complete instructions.

Back to top