Tutorial (API Provider): Adding and Setting Up an API

Follow an example scenario for adding and setting up an API.

Table of Contents

Overview

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, 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 > Agreements section.
  • Upload API Documentation: Add authored API documentation that users can view in the API > Documentation section.

    Note: The platform creates generated documentation automatically from your API definition.

  • Select API Administrators: Send invitations to individuals that you want to give API maintenance privileges to.
  • Invite Users to Private API (optional): Create an API Group and send out invitations to individuals, to invite them to be group members.

Step 1: Add New API

From the top menu bar, choose APIs > Add API.

For full instructions, see Adding an API.

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. Upload the legal agreement 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 the platform using your own HTML editor. Review the following key topics in the Content Development Guidelines for API Admins section to get started. When you are ready to publish your legal agreements to the site, proceed to Step 3: Upload Legal Agreements.

Step 3: Upload Legal Agreements

You can upload completed legal agreements via the File Manager.

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 Agreements 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 API legal agreements? in the Content Development Guidelines for API Admins 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. Go to APIs > My APIs > choose API > Agreements.
  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 add an app? and How do I get API access for my app?

Step 5: Create API Documentation

Each API should offer API documentation. There are two ways you can create it:

  • Generated API doc: If you create a full API design, documentation for your API is automatically generated, in Swagger 2.0 format, and is available for all users of your API.
  • Authored API doc: All authored API documentation must be written and maintained outside 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.

Step 6: Upload API Documentation

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

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 invite someone to be an API administrator

  1. Go to APIs > My APIs > choose API > 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 that you want 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 that you want to send to your invitees.
  5. 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 Action 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 API Scope Groups (for APIs configured with Visibility = Private)

If you API is configured with Visibility = Private, you can use the API Scope Group functionality, which provides a method of creating common interest groups around specific APIs. API Scope Groups are created, or invited, by the API Admin, and are managed by the API Admin.

For complete instructions on creating an API Scope Group, sending out invitations, and assigning group leaders, refer to API Visibility.

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. For complete instructions, see Tutorial (App Developer): Create a New App and Configure It to Consume APIs.