Overview

Switching between roles

Creating a REST API

1. Click Create REST API. The Basic Settings page displays.

   

2. Enter the following details in the Basic Settings section.

   Field	Description
   API Name	Name of the new API. Once you create an API, you cannot change its name.
   Context	Defines a context for a service request. Resources are viewed hierarchically via their URI names, offering consumers a friendly, easily understood hierarchy of resources to leverage in their applications.
   Description	The description of the API.
   Visibility	Visibility settings prevent certain roles from viewing and modifying APIs from another user. Select Public, Intranet, or Partner modes of publishing an API. In Public mode, all levels of users can see an API.
   Version	The version of the API. An API can have multiple versions. The version must always begin with v or V followed by a whole number or decimal. The version can also begin without v or V. For example,
   Make Default	Select this check-box if you want your API version to be the default. If you have multiple versions of the same API, you can choose the one to be the default.
   Lifecycle	Stages of progression of an API. Select from Draft, Published, Deprecated, or Retired.

3. Define the API endpoints. An endpoint defines the address to a web service. You can expose both REST and SOAP services to consumers through APIs. Enter the following details in the Endpoints section.
4. To choose the type of endpoint- HTTP URL or Load Balancer, click Endpoints.

   

5. If you select Load Balancer, choose the load balancing algorithm.

   

   There are two load balancing algorithms that the API Manager uses:
   • Round robin: In this method, the load is balanced sequentially across the API endpoints. All the endpoints are assigned similar load. The endpoints also similar performance. Click Add Another Endpoint to add the endpoint URLs for load distribution.

   

   • Weighted Round Robin: In this method, the load is balanced across the endpoints according to a “weightage” factor that you can assign to each endpoint. The load is divided in terms of the weights assigned. If the weights assigned to the three endpoints are 100, 50, and 50 respectively, the first endpoint handles twice as many requests as the second third endpoints. In the following example:
     • The first endpoint handles the first two requests.
     • The second endpoint handles the third request.
     • The third endpoint handles the fourth request.

   

6. To enable caching of your newly created REST API, click Caching. The benefits of caching an API are speed and reduced load on server. Select the Enable Caching check-box and enter the caching timeout in seconds.
   To enable caching at resource level, select the Apply to all resources check-box. Caching at resource level prevents a separate back-end call to check the authorization type and throttling level of a resource, every time a request to the API comes.

   

7. To enable Cross-Origin Resource Sharing (CORS) of the API, click CORS. CORS allows restricted resources in the API to be accessed from another domain. CORS is a standard mechanism that allows JavaScript calls executed in a web page to interact with resources originating from an external domain. All known browsers enforce this policy.
   To know more about CORS, refer to CORS.

   

Adding resources to the API

1. Enter the name of the resource in the Endpoint Path field. For example, if your endpoint URL represents an online store, you can define the following resources:
   • /products. For example, http://endpointurl/products
   • /orders. For example, http://endpointurl/orders
   • Nested orders, {orderId}/status. For example, http://endpointurl/{orderId}/status
2. Enter a description of the API in the Nickname field. A nickname is a one word description of the API. The resource uses the nickname as an identifier. For example, the nickname /checkPhone can be assigned to the resource /CheckPhoneNumber.
3. Select an HTTP method in the URL to make a request.
4. To add the new resource, click Add Resource. The resource with an HTTP method displays along with the mapped name (the name given to the resource).
5. Click the HTTP method to change the return type, authentication type, rate limits, and scope of the API.
   You can also change the scope of the API resources.
6. Add the query parameters to the API path and modify the properties.
7. To define the output format or response, click Manage Models. You can add or modify a response format and create a return type for a resource.

   

Adding compression methods to request and response

1. Navigate to the properties of a resource in the Edit mode.
2. Choose an appropriate compression type from the Request Encoding and the Response Encoding drop-down lists.

   

3. Click Save.
4. To try out the API, click Test this API. In the tryout mode, update the headers and invoke the API.

Response compression

Request and response logging

Swagger schema to example JSON

Trying out an API

Viewing all APIs

• Published
• Created as draft
• Deprecated
• Retired

• Public
• Partner
• Intranet

API Catalog

Changing the header logo and title

Cross-Origin Resource Sharing (CORS)

Caching

Converting SOAP endpoints to REST endpoints

1. In the General Information section, enter the new API information, such as:
   • API Name
   • Context
   • Visibility
   • Version
   • Description
   • WSDL URL

   

2. In the WSDL URL field, enter a SOAP CFC URL.
   The example WSDL URL has a single port type. A WSDL <portType> element defines a web service, the operations that can be performed, and the messages that are involved.

   

   This WSDL has a single binding. WSDL bindings define the message format and protocol details for a web service. In this case, axis1.cfcSoapBinding is the binding.
   The soap:binding element has two attributes - style and transport. The style attribute can be either rpc or document.
   The transport attribute provides a namespace for a SOAP transportation protocol.
   For example, transport="http://schemas.xmlsoap.org/soap/http" represents SOAP over HTTP.

   

3. Click Fetch. You can see the WSDL resources mapped to REST resources. Choose the port type.

   

4. On the WSDL Mapping Wizard, you can view the list of all the operations of the Axis1 port type.

   

   Expand a method from the list. The REST path of the method displays along with the MIME-type and the method type (GET, PUT, POST, and so forth).

   

   For operations with method type POST or PUT, select the type of parameter for an argument associated with the operation.

   

   • PATHPARAM describes a path parameter in the URL. For example, in the method GET /directory/{directoryName}, {directoryName} is the PATHPARAM.
   • QUERYPARAM describes a parameter of the query string. For example, /search?q=johndoe.
   • FORMPARAM inserts web form parameters into a REST service.
5. To generate the REST resources, click Generate REST Endpoints.  Once you publish, you cannot change the name of the API.
   The REST endpoint displays after the conversion. The new URL is:

   

   The REST endpoint displays after the conversion. The new URL is:

   

   You can use the URL in the following ways:
   To view the swagger resource listing document, enter the following in the address bar of a browser:

   

   You can see the following:

   

   To view the root resource path document, enter the following in the address bar:

   

   You can see the following:

   

6. In the SLA Plans section, select a plan or plans for the API.

   

7. In the Resources section, there is also a list of all SOAP operations that are converted to REST. You can see the methods with each operation.

   

8. Click Publish  to make the REST API available to subscribers.

Importing REST API from ColdFusion

1. On the Create API screen, click Import REST API from ColdFusion.
2. View the list of CF services and click Import  for the service you want to import from CF server.

   

3. Once you generate the resources defined in the cfc, set up the SLA plans and the authentication method for the API. To publish the API, click Publish.

Importing REST API from Swagger

1. On the Create API screen, click Import REST API from Swagger.
   There are three ways by which you can include a Swagger specification:
   1. Using the Swagger link
   2. Using the Swagger text
   3. Importing the Swagger specification from your computer. After uploading a file, you can edit the file and save it. The changes you make do not reflect in your original file.
2. Enter a Swagger API. In this example, use a Petstore server. Click Import.

   

3. Enter the API information and set the visibility.

   

4. Set the authentication type for the API.

   

5. To view existing Petstore resources or add a resource, click Resources on the left pane on the screen.

   

6. To publish the API, click Publish.

Importing a SOAP API

• Apply security authentication to SOAP web services
• Apply rate limiting
• Apply throttling
• Collect metrics and logging information

1. In the API Manager, click Import SOAP API.

   

2. Enter the details on the screen. Set the API visibility to Public. Enter a WSDL URL in the WSDL URL field. For example, enter the WSDL URL http://www.thomas-bayer.com/axis2/services/BLZService?wsdl. 
   This WSDL generates request and response for a web service using which you can fetch Bank Sort Codes (called Bank BLZ codes) for banks in Germany.
3. Click Fetch. You can see both the actual and proxy WSDLs. You can also see the WSDL ports along with their bindings, and actual and proxy SOAP endpoints. For example,

   

4. Choose the type of authentication for the API from the Type  drop-down list.

   

5. Choose an SLA plan or create a plan. To make the plan subject to approval, select the Approval  check-box.

   

   When you make an SLA plan ssubject to approval, an API subscriber cannot use the API unless you grant the subscriber approval to use the API under that SLA plan. For example, if you grant a subscriber GOLD plan subject to approval, the subscriber can only subscribe to GOLD if you approve the subscription request.
   For more information, see Approving subscriptions.
6. To publish the API and make it available to subscribers, click Publish.

Authenticating an API

1. apiKey
2. basicAuth
3. OAuth2

Authentication types

• Header: The api_key header can be used to pass the API Key to the API runtime.
• Query Parameter: The api_key query parameter can be used to pass the API Key.
• Form Parameter: The api_key form parameter can be used to pass the API Key.

1. From the User Store drop-down list, select a user store. The API administrator creates a user store.
2. Create a scope. A scope defines a role defined in a user store. Enter the name of the scope and select a role.
3. To add the newly created scope, click Add Scope.

• The application requests authorization to access resources in an API you create.
• If you approve the request, the application receives an authorization.
• The application requests an access token after it presents authentication of its identity.
• The API issues an access token to the application.

1. Select an Oauth type, USERSTORE or SAML. If you select USERSTORE, select a user store defined in LDAP or database connection.
2. Add a scope.

Adding tiers to an API

1. Select any plan created by the administrator.

   

2. Click the name of the plan and change its properties.
3. Modify the API rate limit. You can only limit an API request rate to number of requests per second, minute, or hour.

   

4. Modify the API throttle limit. You can only limit an API throttle rate to number of requests per day, week, or month.

   

5. Select the type of limit for the API requests.
   There are two options:
   • Hard: If you select this option, the number of API requests cannot exceed the throttle limit.
   • Soft: If you select this option, you can set the API request limit exceed a percentage. For example, if you set the Exceed Limit to 90%, the number of API requests can exceed 90% of the prescribed limit.

   

6. To approve an API request plan, select the Approval check-box.
7. To add the new SLA plan, click Add Plan.

Adding rate limits to API resources

1. Enter the number of requests for an SLA plan.
2. Save the information. The API resources get new rate limits.

Specifying endpoints

• Round Robin: In this method, the load is balanced sequentially across the API endpoints. All the endpoints are assigned similar load and have similar performance. Click Add Another Endpoint to add the endpoint URLs for load distribution.
• Weighted Round Robin: In this method, the load is balanced across the endpoints according to a "weightage" factor that you can assign to each endpoint. The load is divided in terms of the weights assigned. If the weights assigned to the three endpoints are 100, 50, and 50 respectively, the first endpoint handles twice as many requests as the second and third endpoints.

• Client Authentication: If you choose this option, you must choose the key store and the key pair you have created. 
• Shared Secret: If you choose this option, you must specify the shared secret token. A shared secret helps in authenticating against all other endpoints. If you do not have a shared secret token, you can generate the token.

API Policies

• Data transformation policies
• Threat protection policies

Content Type Restriction

XML Threat Protection

JSON Structure Limits Policies

IP Access Control Protection

HTTP Message Limits

XML to JSON Transformation

JSON to XML Transformation

Error codes for policies

Key Stores

• The keystore contains private keys and certificates used by SSL servers to authenticate themselves to SSL clients. By convention, such files are referred to as keystores .
• When used as a  truststore , the file contains certificates of trusted SSL servers, or of Certificate Authorities trusted to identify servers. There are no private keys in the truststore .

Adding the API business details

Approving subscriptions to an API

Deleting a subscriber

Viewing subscribed users

• User name
• First and last name
• Email id
• Phone
• Action

Viewing notifications

• Request to approve API subscription
• Approved API subscription
• Termination or deprecation of an API
• Errors in API endpoints
• An SLA reaches its limits

Publishing the API

Viewing the analytics dashboard

• Home
• APIs
• APIs and Versions
• Developers
• Errors

Filtering data according to time range

1. Quick
2. Relative
3. Absolute

1. Click the time filter as shown below:

   

2. Select any time range from the list, as shown below:

   

   If you select Today, you can see the analytics of all APIs for the last 24 hours.
3. Click Relative. You can filter the data from a specified date and time to the current date and time.

   

4. Click Absolute. You can filter the results according to dates.

   

Creating a visualization

1. To create a visualization, click the Visualize tab.

   

2. You can create visualizations in the form of area charts, data table, pie charts, and so on, from API information. As an example, create a pie chart from the API analytics. Click Pie chart from the list.

   

3. Select from the following:
   
4. Create a visualization from a new search. Select From a new search. You can see a pie-chart representaion of the number of new APIs by a publisher.

   

5. Select the type of pie-chart from the following:
   • Split Slices
   • Split Chart

   

6. Select Split Slices and select Date Histogram from the Aggregation drop-down list.

   

7. Click Apply. A split pie-chart displays according to the parameters, which in this case is timestamp.

   

Field-based filtering

1. Click any dashboard type:
   • Home
   • APIs
   • API and Versions
   • Developers
   • Errors
2. Choose any dashboard and hover your mouse on the graph to view the fields and the values. The snapshot below displays the field values for the top five API request count dashboard:

   

   You can see a table that lists all the field values for a particular API and the number of times the API is called.
3. Click the graph. You can see the field-level filters on top of the dashboard.

   

4. Select or clear a filter and click Apply Now. You can see that all dashboards change according to the filters enabling you to have a granular view of an API. The snapshot below now represents the field values for the API usweather.