Creating an API

Before You Begin

This 20-minute tutorial shows you how to create an API on the Apiary platform and how to manage the API using the Oracle API Platform Cloud Service. After your API is created, you will also learn how to invoke it by using a REST client.

Background

Oracle API Platform Cloud Service offers an easy way to manage, secure, and publish services for application developers. You can create APIs that expose the functionality of your organization's back-end systems or other services.

In this tutorial, you are an API Manager working for NextGen company. You have been tasked with creating an API for mobile devices. You create your WarrantyClaim API on the Apiary platform and in the Management Portal, you configure and deploy it. To verify your API, you invoke it using the REST client.

What Do You Need?

• An account on Apiary
• Access to an Oracle API Platform Cloud Service instance with the API Manager role and the Deploy API Grant assigned
• An active gateway in Oracle API Platform Cloud Service to deploy your APIs
• A REST client tool

Design an API in Apiary

1. Download the warrantyclaim.yml file (download) into a local directory on your system. This file contains the Swagger API that will be published in Apiary. It also contains the sample data that's used as the service response.
2. Open a browser window and go to Apiary: https://apiary.io/
3. On the Apiary Sign in page, provide your email address and password, and then click Sign in.
4. The first time you log in to Apiary, enter Warranty Claim as the name of your first API, and then click the down arrow to select the Swagger option. Click SAVE AND START USING APIARY.

   

5. On the Editor page, replace the existing text with the contents of the warrantyClaim.yml Swagger file.

   The document is automatically validated.

   

6. Click Save.

   If you have trouble saving the document, then verify that the text is copied correctly as it appears in the Swagger file.

7. Click Inspector.

   On the Inspector page, note the listening URL of your API.

   

Create an API

1. Sign in to the API Platform Cloud Service Management Portal by entering the following URL format: https://instance-identityDomain>.apiplatform.ocp.oraclecloud.com/apiplatform/management

   Where, instance-identitydomain refers to the identity domain of your Oracle API Platform Cloud Service instance. For example, https://apidemo-paasproducm.apiplatform.ocp.oraclecloud.com/apiplatform/management

2. On the API Platform Cloud Management Portal login page, enter your user name and password, and then click Sign In.
3. In the Management Portal navigation menu, click APIs.

   

4. On the APIs page, click Create.
5. In the Create API dialog, enter the following values: 
   • Name: Warranty Claim
   • Version: 1
6. Click Create to create a new API.

   

Configure the API Request URL

1. On the APIs page, click Warranty Claim.
2. In the API's navigation pane, click API Implementation .
3. On the API Implementation page, hover the mouse over the API Request section and then click Edit.
4. In the Edit Policy dialog, select HTTP from the Protocol drop-down list, enter warrantyclaim/1 in the API Endpoint URL field, and then click Apply. 

   

5. Click Save to save the changes.

Configure the Service Request URL

1. On the API Implementation page, hover the mouse over the Service Request section and then click Edit.
2. In the Edit Policy dialog, expand the Configure Headers section. From the all the Headers list, select Pass through and from the Drop Headers list, select the Accept-Datetime header name.

   

3. In the Service section, select Enter a URL and then specify the API URL from Apiary. If you have set up your gateway node in your corporate Intranet and a proxy that is required to reach to the external addresses, then select the Use Gateway Node Proxy check box.

   

4. Click Apply and then click Save to save your changes.

Issue API Grants

1. In the API's navigation pane, click Grants .
2. On the Grants page, the default Manage API tab is selected. Click Add Grantee to add users who can access the API.
3. In the Add Grantee dialog, select the user(s) or group(s) to which you want to issue the grant. You can select multiple users and groups. Click Add.

   

   The API grant is issued to the users you chose.

   

Deploy the API

1. In the API's navigation pane, click Deployments .
2. On the Deployments page, click Deploy API.
3. In the Deploy API dialog, select the gateway you want to deploy to and set the Initial Deployment State to Active to deploy the API in an active state and then click Deploy.

   

4. Now, your API is deployed to the production gateway. Verify that the runtime state appears as ACTIVE before testing your API and note the Load Balancer URL to invoke your API.

   

Invoke the API

1. Get the Load Balancer URL for your API from the previous section. For example, http://example.com/warrantyclaim/1
2. Open the REST client tool of your choice to invoke the API.
3. Set the verb, for example GET. Optionally set the header, and then send the request to the API. The following example shows how to invoke the API using the GET request:

   curl -X GET 
     -H 'Accept: application/json' 
     -H 'Content-Type: application/json'
   'http://example.com/warrantyclaim/1/tickets'
   

   Where, example.com refers to the path of the gateway where API is deployed, warrantyclaim refers to your API, tickets refers to a resource defined in your API.

   Note: In this scenario, the Apiary document represents the back end service. In a production environment, a separate Apiary document should be created for an API that will be published to a gateway, as its interactions are altered by the gateway policies.

Want to Learn More?

• Manage APIs in the Oracle Help Center