Publish an API

If you are an API Provider, follow the API setup process to configure your API, add legal agreements and API documentation, test your API by creating an app and requesting access using the API Access Request function, and perform administrative tasks.

Quick Start

Is there a quick start procedure for the API setup process?

API Publishing

What are API's?

What is a Private API?

What are the recommended API development best practices?

What is the minimum requirement for adding an API?

What security and monitoring policies does SOA Software Open support?

How do I add an API to SOA Software Open?

How do I add a REST service to SOA Software Open?

How do I manage API visibility?

What is a Proxy API?

What is the difference between Sandbox and Production environments?

What is an API Type Profile?

What are the supported Methods and Content Types for Requests?

What are the supported Methods and Content Types for Requests?

How do I add an API version?

How do I edit an API?

How do I delete an API?

OAuth Support

What is OAuth?

What OAuth versions does SOA Software Open support?

How do I set up an SOA Software Open deployment to support OAuth?

How do I configure my API with an OAuth Provider?

What's the difference between an SOA Software Open OAuth Provider and 3rd Party Provider?

What grant types does OAuth support?

How does OAuth 2-Legged and 3-Legged Authorization work?

What is a Refresh Token?

What is an Access Token?

What is a Grant Property?

How does Login Branding work?

What is an Authorization Server and how does it work?

What are the OAuth 2.0 Endpoints and how do they work?

What are the OAuth 1.0a endpoints?

What is Authorization Server Client Authentication Policy?

How does Resource Mapping work?

OpenID Support

What is OpenID?

What OpenID versions does SOA Software Open support?

How do I set up an SOA Software Open deployment to support OpenID?

How do I configure my API with an OpenID Provider?

What is a Discovery URL?

What is a Realm?

API Documentation Maintenance

What is the API documentation maintenance process?

Who can update API documentation content in SOA Software Open?

How do I add API documentation to SOA Software Open?

Can I link to API documentation on a different site?

What are the content guidelines for API documentation?

Legal Agreement Maintenance

What is the legal agreement maintenance process?

Who can update legal agreement content in SOA Software Open?

How do I add a legal agreement?

What are the content guidelines for legal agreements?

How do I activate a legal agreement?

How do I deactivate a legal agreement?

How do I edit legal agreement details?

How do I download a legal agreement report?

Groups

How do I create a Private API Group?

What happens after accept an invitation to a Private API Group?

Admin Management

What are the components of the Admin page?

How do I invite people to be administrators for my API?

How do I invite SOA Software Open non-members to be administrators of my API?

How do I respond to an API administrator invitation?

How do I cancel an API administrator invitation?

How do I remove an API administrator from my API?

Quick Start

Is there a quick start procedure for the API setup process?

If you are an API provider, click here for an end to end walkthrough of the API setup process. The walkthrough covers:

Back to top

API Publishing

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?

SOA Software Open supports public and private APIs. Public APIs are visible to SOA Software Open visitors and members. Private APIs are visible to SOA Software Open members who have been invited to join a Private API Group. Once an SOA Software Open member has accepted an invitation to a Private API Group, the Private API is displayed with a unique icon throughout the member’s SOA Software Open experience.

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.  A key consideration when building an API includes:


  1. Is the API atomic and well documented?
  2. 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:

  1. Is the API secure?

    The API must be robust and managed. To achieve this you must provide developers with feedback that the API will perform reliably in terms of functionality, performance, and its ability to security the customer data.

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 SOA Software Open 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 SOA Software Open 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 SOA Software Open using the API Board, trouble ticket management system, and by submitting a support request to SOA Software Customer Support.

Back to top

What is the minimum requirement for adding an API?

The minimum requirement to add an API to SOA Software Open, is that it must have an endpoint. For example:

Back to top

What security and monitoring policies does SOA Software Open support?

SOA Software Open 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.

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, contact SOA Software Customer Support.

Back to top

How do I add an API to SOA Software Open?

SOA Software Open 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.

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 SOA Software Open API search results.

An SOA Software Open 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 using SOA Software Open, select the Yes radio button in the Proxy API section. There are many benefits to proxying your API with SOA Software Open including utilizing SOA Software Open 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).

To add an API:

A. Launch the Add a New API Wizard

The first step in the process is to launch the wizard. 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 the information you specify 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 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 in the "Target URL" field. 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, and select Operational and/or Service Level 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 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. 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 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 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. The 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.
    • 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. 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.
  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.

Back to top

How do I add a REST service to SOA Software Open?

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 SOA Software Open Plus menu, select Add a New API.
  2. On the API page, specify the information as illustrated below, and click Next to continue.

  3. 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.

  4. Configure the following information:
    • On the Proxy page, enter the URL and CNAME of the Production Endpoint.
    • Expand Advanced Options and verify the settings are correct (i.e., they match the Target section in the previous step).
    • Click Save.

B. Setup Contract

  1. Add a new app. See How do I create a new app in SOA Software Open?
  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 SOA Software Open 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 SOA Software Open 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 SOA Software Open 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 SOA Software Open 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 in SOA Software Open:

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 in SOA Software Open:

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 Methods and Content Types for Requests?

If you chose to proxy your API with SOA Software Open, 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. SOA Software Open 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. SOA Software Open 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

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 currernt 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 a 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, 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 an API to SOA Software Open? or How do I add and setup an API in SOA Software Open? 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?

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 a API you would like to edit. The API Details page displays.
  3. From the Version drop-down menu, select the API version you would like to edit.
  4. Click Edit. The Edit API Info screen displays and presents the current API definition.
  5. Update the API contents based on your requirements. See How do I add an API to SOA Software Open? or How do I add and setup an API in SOA Software Open? for details on configuring your API.
  6. After you have edited your API, click Save.

Back to top

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 a 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, the following message displays "Deleting the last API version will delete the API too. Do you want to proceed?" Click OK to delete the API or Cancel to exit the operation.

Back to top

OAuth Support

What is OAuth?

OAuth is an open standard security protocol for authorization that allows you to share private resources stored on one site with another site without having to share credentials.

One advantage of OAuth is that it supports both authentication and authorization in such a way that an application does not need to give access to the users credentials. For example, in the SOA Software Open you can sign in using your Facebook credentials, or on the API Details page you can share an API to Facebook, Twitter, and Linked In. These elements of the SOA Software Open site are configured as private resources.

In addition, OAuth can potentially extend the userbase of your APIs and applications by providing a flexible, familiar way to access them. For example, if you have multiple APIs added to the SOA Software Open repository, and each API has granted access to multiple apps, you then have a broadened developer community, in addition the substantial number of users that are using the applications.

Access permissions are initially established by supplying a Resource that is dictated by the application (e.g., username/password, email address.). For example, if you supply username and password tokens, each token grants access to a specific site for a specific resource for a defined duration. This allows you to grant a third party site access to their information stored with another service provider, without sharing their access permissions or the full extent of their data.

OAuth 2.0 defines the following roles of users and applications:

OAuth in the context of an API in SOA Software Open includes the following actors:

Back to top

What OAuth versions does SOA Software Open support?

SOA Software Open supports both the 1.0a and 2.0 versions of OAuth.

Back to top

How do I set up an SOA Software Open deployment to support OAuth?

If you are a Site or API Administrator you can set up OAuth Provider definitions in the Site Administration > Domains section. You create a domain for each OAuth Provider scenario and these configurations are then available for selection using the API OAuth function in the APIs that are part of your SOA Software Open deployment.

Back to top

How do I configure my API with an OAuth Provider?

If your API currently supports OAuth it must be associated with an OAuth Provider configuration that represents the OAuth use case that is most appropriate for the intended usage of the API, and resource mapping must be configured for selected operations to establish authorization permissions. This is accomplished using the OAuth Details function on the API Details page.

Process:

A. API Administrator Installs OAuth Provider Features

After an API Administrator adds an API, they then define one or more OAuth Provider configurations:

B. Launch OAuth Details Wizard and Select OAuth Provider

The first step is to select an OAuth Provider for both the Production and Sandbox endpoints of your API.

  1. On the API > Details page, click OAuth Details. The API OAuth Wizard launches and the Provider page displays.
  2. Based on your API configuration you will have one or more Production or Sandbox endpoints. In the OAuth Provider section select a provider name for each endpoint you would like to configure.
    • If you are configure a Proxy API, select a pre-defined OAuth Provider.
    • If you are configuring the Target API, select 3rd Party Provider.
    • After selecting a provider the wizard updates to reflect the elements that comprise the provider definition.

C. Specify Authorization Details

Based on the OAuth version supported for the provider selected, specify the details for 1.0a or 2.0 OAuth Versions. If you select OAuth 2.0, the OAuth Options section displays where you can configure Authorization Grant Types.

Note: When specifying an Authorization Server URL in SOA Software Open, it's important to verify that the client application is authorized to use the grant type that the OAuth Provider is configured to support.

  1. Select an OAuth version. Version 2.0 and 1.0a are supported.
  2. Specify the required endpoint URL's for each OAuth version
    • Click here for information on OAuth 2.0 endpoints.
    • Click here for information on OAuth 1.0a endpoints.
  3. If you selected OAuth 2.0, select an Authorization Grant Type and Authorization Server Client Authentication Policy.
    • Click here for information on Authorization Grants.
    • Click here for information on Client Authentication Policies.

D. Configure Resource Mapping

If you selected a predefined OAuth Provider, the resources (i.e., operations) of the current API have already been defined and authorized for use. On the Resource Mapping page, you identify which the operations your applications will need to get authorization for and the resource scope. For example, Application1 includes a calendar and may need access to the API's calendar resource, and Application2 includes an email client and may require access to the API's address resource.

  1. Click the radio button of the Resource Mapping approach you would like to use. API-wide Mapping or Operation Specific Mapping.
  2. In the "Select Resource Scope" section specify the "Resource URL" or "Scope ID" for each Operation, then deselect the checkboxes of operations you do not want to include in the configuration.
    • Click here for more information on Resource Mapping.
  3. After completing your configuration, click Save.

Back to top

What's the difference between an SOA Software Open OAuth Provider and a 3rd Party Provider?

An Identity Provider is a central OAuth enabled provider that provides both user authentication and user authorization. Using the API OAuth function, you can select a pre-defined OAuth Provider or a 3rd Party Provider:

Reference: API > API Details > OAuth Details > OAuth Provider

Back to top

What grant types does OAuth support?

Access or permission to use a resource by an OAuth Provider is facilitated using grants.

Note: SOA Software Open supports all four grant types for OAuth 2.0, and Authentication Code only for OAuth 1.0a.

OAuth defines the following grant types that reflect different authorization mechanisms:

2-Legged

The following grant types are used in the 2-Legged OAuth scenario.

Grant Type Description
Client Credentials The client presents its own credentials to the OAuth Authorization Server in order to obtain an access token. This access token is either associated with the client’s own resources, and not a particular resource owner, or is associated with a resource owner for whom the client is otherwise authorized to act.
Resource Owner Password Credentials The client collects the resource owner’s password and exchanges it at the OAuth AS for an access token, and often a refresh token (see below). This grant type is suitable in cases where the RO has a trust relationship with the client, such as its computer operation system or a highly privileged application since the client must discard the password after using it to obtain the access token.

3-Legged

The following grant types are used in the 3-Legged OAuth scenario.

Grant Type Description
Authorization Code An authorization code is returned to the client through a browser redirect after the resource owner gives consent to the OAuth Authorization Server. The client then exchanges the authorization code for an access token. Resource owner credentials are never exposed to the client.
Implicit

An access token is returned to the client through a browser redirect in response to the resource owner authorization request.

This grant type is suitable for clients that do not support keeping client credentials confidential (for use in authenticating with the OAuth Authentication Server) such as client applications implemented in a browser using a scripting language like Javascript.

Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > 3-Legged / 2-Legged Grant Types

Back to top

How does OAuth 2-Legged and 3-Legged Authorization Work?

The number of legs used to describe an OAuth request typically refers to the number of parties involved. Legs generally mean that access is shared by the client with other clients.

This section provides a brief description of 3-Legged versus 2-Legged OAuth:

3-Legged:

In 3-Legged OAuth a resource owner wants to give a client access to a server without sharing their credentials (i.e. username/password). For example, a user (resource owner) wants to give a third-party application (client) access to his Twitter account (server).

This scenario works as follows:

2-Legged:

2-Legged OAuth describes a typical client-server scenario without any user involvement. For example, a local Twitter client application accessing your Twitter account.

This 2-legged OAuth scenario consists of the first and last steps of 3-legged OAuth:

Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > 3-Legged / 2-Legged Grant Types

Back to top

What is a Refresh Token?

Refresh Tokens are credentials used to obtain access token:

Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > Issue Refresh Tokens

Back to top

What is an Access Token?

An access token is issued as a string that represents an access authorization issued to the client. It is used by the client to access protected resources hosted by the resource server. Access tokens are issued to clients by an authorization server with the approval of the resource owner. Each access token includes an expiration attribute that indicates how long the token is valid.

Note: An access token timeout is typically 15 days (or 1296000 seconds).

OAuth 2.0:

There are two types of access tokens:

As part of the OAuth Provider Domain configuration process, the Add Domain Wizard requires that you select what kind of token should be issued (Bearer or Mac).

OAuth 1.0a:

A token shared secret is issued one-time only.

Reference: Site Administrator > Domains > Configure OAuth Provider > Grant Types > Access Token Type

Back to top

What is a Grant Property?

A grant property is a custom property that a resource owner can define in the client application to apply restrictions to the grant. Grant properties provide a value-added service to the grant by providing support to avoid the misuse of a grant and flexibility by extending the types of use cases that can be configured for grants.

Grant properties are initially defined in the client application and assigned a "tag." The Site Administrator or API Provider can then reference the grant properties in the OAuth Provider domain by specifying a Property ID (which represents the Tag of the property definition) and Property Label (which is a description label that is internal to SOA Software Open).

After you have successfully logged into your application via the login screen associated with the OAuth Provider the API, an app authorization screen displays that typically includes some type of authorize option and can optionally include fields for entering any custom grant properties data. Here you enter the values for the grant properties, and click Authorize (or equivalent option). A token is given to the application and an authorization successful message is returned. The application can then use this token to start sending requests. The grant properties are then sent back to the client application for validation.

Example:

Reference: Site Administrator > Domains > Configure OAuth Provider > Properties

Back to top

How does Login Branding work?

When a user logs into your application using the OAuth Provider configuration, they must see a login screen that is custom branded to your organization. You can customize the login with a unique logo that represents your organization, footer text (e.g., copyright information), and the URL you want to offer to Resource Owners and applications to access this OAuth provider capabilities.

Reference: Site Administrator > Domains > Configure OAuth Provider > Branding

Back to top

What is an Authorization Server and how does it work?

An authentication server is an application that facilitates authentication of an entity that attempts to access a network. Such an entity may be a human user or another server. An authentication server can reside in a dedicated computer, an Ethernet switch, an access point or a network access server.

Authentication Servers can be set up in a variety of ways, depending upon the security scheme of the network they are serving. The basic process for authenticating a user includes the following steps:

Back to top

What are the OAuth 2.0 Endpoints and how do they work?

OAuth 2.0 defines an Authorization, Token, and Redirection endpoints. They are typically a URI on a web server. 

API Administrators who are defining OAuth Providers using the Add OAuth Wizard (via Site Administration > Domains) or are configuring OAuth for a specific API using the API OAuth Wizard (via API > Details) will specify an Authorization URL, Token Endpoint URL, and Redirection URL if they are using OAuth 2.0.

This section provides a brief overview of how an Authorization Server works in respect to each endpoint:

OAuth 2.0 Endpoints:

Authorization Server Workflow:

Back to top

What are the OAuth 1.0a Endpoints?

OAuth 1.0a supports the following endpoints:

For more information on these endpoint types, refer to the OAuth Core 1.0, Revision A specification (http://oauth.net/core/1.0a/)

Back to top

What is an Authorization Server Client Authentication Policy?

If you are using the Policy Manager Network Director as the Authentication Server specified in your OAuth configuration, SOA Software Open provides a series of client authentication policies that can be used to authenticate the client's credentials:

Back to top

How does Resource Mapping work?

Operations in an API act on data objects called resources. Resources are permissions that OAuth can read to get access to specified operations from one site to another.

Although the approach for organizing API Resources varies from API to API, the resources are typically organized as follows:

A base set of resources are initially defined in the OAuth Provider domain and the API provider can perform additional filtering when on the resource list when configuring the API OAuth Wizard. The API OAuth Wizard includes a Resource Mapping section that allows you to specify a Resource Scope for selected operations, or enable API-wide Mapping. For Operation-specific Mapping you specify the Resource URL or symbol {id}, for API-wide Mapping you specify the Resource URL of the Root Node.

Resources are defined in a hierarchy of permissions that represent the list of actions to be performed. For example, if you have a credit card service API, you may have resources like Charge Account, Deposit, Cash Advance, or Get Statement, in addition to account management services like Add Card, Report Fraud Transaction, etc.  Resources are generally added to the hierarchy based on a logical sequence. For example, if your credit card service API has tha ability to deposit, you might make Deposit a sub-resource under Withdraw.  

Back to top

OpenID Support

What is OpenID?

OpenID is an open decentralized standard for authenticating users. It can be used for access control and allows users to log on to different services with the same digital identity where these services trust the authentication body. OpenID simplifies the authentication process because only one username and password to remember.

OpenID 2.0 defines the following roles of users and applications:

Back to top

How do I set up an SOA Software Open deployment to support OpenID?

If you are a Site or API Administrator you can set up OAuth Provider definitions in the Site Administration > Domains section. You create a domain for each OpenID Provider scenario and these configurations are then available for selection using the API OAuth function in the APIs that are part of your SOA Software Open deployment.

Back to top

What is a Relying Party?

A Relying Party is service provider (e.g., website, application) that can verify the end-user's identifier. The OpenID Provider is a service that specializes in registering OpenID URLs or XRIs. OpenID enables an end-user to communicate with a relying party. This communication is done through the exchange of an identifier (e.g., URL or XRI chosen by the end-user to name the end-user's identity). An OpenID Provider provides the OpenID authentication.

The relying party discovers the OpenID provider URL by requesting the XRDS document (i.e., Yadis document), with the content type application/xrds+xml. This document may be available at the target URL and is always available for a target XRI. The exchange is enabled by a User-agent, which is the program (such as a browser) used by the end-user to communicate with the relying party and OpenID provider.

Back to top

What OpenID versions does SOA Software Open support?

SOA Software Open supports version 2.0 of OpenID using OAuth 2.0 or OAuth 1.0a.

Back to top

Whats the difference between using OpenID versus OAuth for authentication?

The difference between using OpenID versus OAuth for authentication is as follows:

If the user grants access, the application retrieves the identifier for establishing the identity using the APIs. In both cases access to the Identity Provider involves authentication to the Identity Provider.

Summary:

Back to top

How do I configure my API with an OpenID Provider?

There are two ways you can configure your API with an OpenID Provider. Using the OAuth Details function on the API Details page, you can configure OAuth for your API and:

Back to top

What is a Discovery URL?

An OpenID discovery URL represents the location of the relying party's OpenID endpoints that are published using the Yadis protocol. OpenID 2.0 providers advertise the location of their endpoints, as well as the versions and extensions that they support using Yadis. For example, the Google discovery URL is (https://www.google.com/accounts/o8/id).

The OpenID provider verifies a relying party's realm and endpoints by making a Yadis request to the openid.realm to discover the realm's OpenID endpoints. If the OpenID Provider is unable to verify the realm and endpoints, the user will be warned that the user is signing into an unverified site.

Back to top

What is a Realm?

A "realm" is a pattern that represents the part of URL-space for which an OpenID Authentication request is valid. A realm is designed to give the end user an indication of the scope of the authentication request. OpenID providers must present the realm when requesting the end user's approval for an authentication request. The realm must be used by OpenID providers to uniquely identify Relying Parties. For example, OpenID providers may use the realm to allow the end user to automate approval of authentication requests.

Back to top

API Documentation Maintenance

What is the API documentation maintenance process?

All API documentation must be developed and maintained outside of SOA Software Open in your own HTML editor. Each time a content update is made, it must be uploaded to the SOA Software Open site. See Content Development Guidelines.

Back to top

Who can update API documentation content in SOA Software Open?

API documentation can be updated by the owner of the API (API Administrator). The API Administrator can also assign team members that have accepted invitations to be administrators of the API with documentation update privileges.

Back to top

How do I add API documentation to SOA Software Open?

You can add documentation for your API to the API > Documents section by uploading content using the SOA Software Open File Explorer or by adding API documentation using the Swagger documentation tool that is integrated with SOA Software Open. See Content Development Guidelines for details.

Back to top

Can I link to API documentation on a different site?

Yes. If you already have a website established for your API and/or your documentation, you can upload a file that includes introductory text and includes a link to your website. See Content Development Guidelines for details.

Back to top

What are the content guidelines for API documentation?

SOA Software Open provides a set of content development guidelines for API documentation. See Content Development Guidelines for details.

Back to top

Legal Agreement Maintenance

What is the legal agreement maintenance process?

The legal agreement maintenance process includes the following steps.

Back to top

Who can update legal agreement content in SOA Software Open?

API legal agreements can be updated by the owner of the API (API Administrator). The API Administrator can also assign team members that have accepted invitations to be administrators of the API with legal agreement update privileges.

Back to top

How do I add a legal agreement?

You can add a legal agreement by uploading content using the SOA Software Open File Explorer. See Content Development Guidelines for details.

Back to top

What are the content guidelines for legal agreements?

SOA Software Open provides a set of content development guidelines for all types of content including legal agreements. See Content Development Guidelines for details.

Back to top

How do I activate a legal agreement?

After legal agreements have been uploaded and the name and description have been assigned, the agreements must be activated. An activated legal agreement displays in the SOA Software Open API Access Wizard where it can be reviewed and accepted as part of the API access request process.

To activate a legal agreement:

  1. Navigate to API > API Name > Legal.
  2. Click Manage Agreements.
  3. Choose which legal agreement you would like to activate. In the Status column, click Activate. The legal agreement will be activated and added to the SOA Software Open API Access Wizard.

Back to top

How do I deactivate a legal agreement?

If for any reason it becomes necessary to discontinue use of a particular legal agreement, you can deactivate it and remove it from displaying in the SOA Software Open API Access Wizard.

To deactivate a legal agreement:

  1. Navigate to API > API Name > Legal.
  2. Click Manage Agreements.
  3. Choose which legal agreement you would like to deactivate. In the Status column, click Deactivate. The legal agreement will be deactivated and removed from the SOA Software Open API Access Wizard.

Back to top

How do I edit legal agreement details?

After you have activated a legal agreement you can update the name and description using the Edit function. This information displays on the Agreements Summary listing of your legal agreement. The "Name" assignment also is used as the hyperlinked display name of the legal agreement on the Legal page. The Edit function in the Status column is used to update legal agreement display information.

To edit a legal agreement:

  1. Navigate to API > API Name > Legal.
  2. Click Manage Agreements.
  3. Choose which legal agreement you would like to edit. In the Status column, click Edit. The Edit pop-up displays.
  4. Specify a Name and Description for your legal agreement. Click Save to commit your changes.

Back to top

How do I download a legal agreement report?

If you would like to view statistics of legal agreement activation or deactivation activity, you can download a CSV file that includes the legal agreement name and username/date/time stamp of when the legal agreement was activated or deactivated.

To download a legal agreement report:

  1. Navigate to API > API Name > Legal.
  2. Click Manage Agreements.
  3. Choose which legal agreement you would like to view a report for. In the Status column, click Report. From the file dialog, navigate to the directory where you would like to save the .CSV file and click Save.

Back to top

Groups

How do I create a Private API Group?

If you've added a Private API to SOA Software Open (i.e., visibility = Private), SOA Software Open provides a Private API Group collaboration function via the API > Groups page. See the Groups section of Collaborate for more information.

Back to top

What happens after I accept an invitation to a Private API?

If you receive an invitation to a Private API, and accept the invitation:

Back to top

Admin Management

What are the components of the Admins page?

The APIs section includes an Admins page that allows you to invite others to be administrators for your API. API administrators can then be viewed and managed in a summary listing.

Invite Administrators

The Invite More function allows you to invite additional users to be administrators for your API.

View Administrators

When an administrator invitation is submitted, the username, email address, and invitation status (i.e., Email Sent, Approved, or Rejected) of the invitee is added to the Admins Summary.

Manage Administrators

API Administrators can remove an Administrator from the listing.

Back to top

How do I invite people to be administrators for my API?

The API > Admins page includes an administrator invitation function that allows you to invite people to be administrators for your API.

To do this:

  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.

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.

Back to top

How do I invite non-members to be administrators of my API?

You can invite non-members to be administrator of an API, but in order for the invitee to accept the invitation, they must be an SOA Software Open members. See Getting Started for sign up information.

Back to top

How do I respond to an API administrator invitation?

If you receive an invitation via email to be an administrator of an SOA Software Open API you can accept or reject the invitation.

To accept an API administrator invitation:

  1. Click the link in the API administrator invitation email, log into SOA Software Open, and go to your Dashboard page.
  2. Choose your API administrator invitation in the newsfeed.
  3. To accept the API administrator invitation, click Accept. The Accept this invitation text box displays. Enter a comment (if applicable) and click Confirm. The status changes to Invitation Accepted.
  4. To view administrators for the API, click My APIs > Admins. The Admins page displays. Your username, email address, and Accepted team status displays. You can also view other members of the development team.

To decline an API administrator invitation:

  1. Click the link in the API administrator invitation email, log into SOA Software Open, and go to your Dashboard page.
  2. Choose your API administrator invitation in the newsfeed.
  3. To decline an API administrator invitation, click Decline. The Decline this invitation text box displays. Enter a comment (if applicable) and click Confirm. The status changes to Invitation Declined.

Back to top

How do I cancel an API administrator invitation?

Once an invitation is sent to an individual you would like to be an API administrator, the invitation itself cannot be revoked. An SOA Software Open member can choose to accept or decline the invitation. If they choose to accept the invitation, you can remove the API administrator from your API by clicking Remove. See How do I remove an API administrator from my API?

Back to top

How do I remove an API administrator from my API?

Any API administrator can remove other administrators from the API. To do this:

  1. Navigate to My APIs > API Name > Admins. The Admins page displays.
  2. To remove an API administrator from an API, choose the line item of the API administrator and click Remove.

Back to top