Quick Start (API Provider)


How do I add and setup an API in SOA Software Open?

The API setup process involves adding an API to SOA Software Open, 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:

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.

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.

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 URL. 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, and select policies 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 Operation and specify the operations for the API definiton 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. See How do I add a REST service to SOA Software Open? for a sample walkthrough.

Select Policies:

  1. In the Policies section, security monitoring policies are selected by default. Click Next to continue. See What security and monitoring policies does SOA Software Open support?

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 SOA Software Open 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 SOA Software Open 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.
    • Specify the protocol from the URL drop-down menu. Supported protocol options include HTTP and HTTPS.
    • Enter the URL Path.
    • 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. 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.
  2. 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.
  3. On the Advanced Options line click Show to expand the section.
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, URL, 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, security monitoring policies are selected by default. Click Next to continue. See What security and monitoring policies does SOA Software Open support?
  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 developers 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 SOA Software Open API Access Wizard.

All legal agreements must be written and maintained outside of SOA Software Open 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 SOA Software Open site, proceed to Step 3: Upload Legal Agreements.

Step 3: Upload Legal Agreements

You can upload completed legal agreements via the SOA Software Open File Explorer.

Here are some points to consider:

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 SOA Software Open 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 for section in the SOA Software Open 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 in SOA Software Open? 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 SOA Software Open 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 SOA Software Open site, proceed to Step 6: Upload API Documentation.

Step 6: Upload API Documentation

You can upload API documentation via the SOA Software Open File Explorer. 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 SOA Software Open, 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 will be sent to the invitee.
  6. After the email invitation is sent, SOA Software Open will post an administrator invitation to the SOA Software Open member's Dashboard. The invited SOA Software Open member can then log into SOA Software Open 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 SOA Software Open 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