Implementing APIs in Oracle API Platform Cloud Service


Options



Before You Begin

Purpose

In this tutorial, as an API Manager user, you learn how to create your own APIs on the Apiary platform and Oracle API Platform Cloud Service so that you can manage and secure your endpoints. After your API implementation is ready, you also learn how to invoke it by using a REST client.

Time to Complete

1 hour

Background

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

Oracle API Platform Cloud Service leverages the following functionality to overcome common challenges and fundamentally change the way application developers work by building and publishing APIs that share enterprise services and data in the cloud:

  • Automated provisioning
  • Create and secure APIs
  • Edit and publish APIs
  • Discover, understand, and subscribe to APIs
  • Control API access at runtime and monitor API performance

Scenario

In this scenario, you work for an energy company. Your organization has back-end services that return billing and usage information for the most recent billing periods when provided with a customer ID number.

You want to expose this information as a single API to your company’s mobile developers so that they can develop a new mobile application for your customers.

Context

This is the first tutorial in a series of nine that shows you how to manage and secure your APIs in Oracle API Platform Cloud Service and invoke them from a REST client.

What Do You Need?

Building an API in Apiary

In this section, you build an API on the Apiary platform by using a Swagger API Description file that generates an API that returns mock data as the response.

  1. Download the gas_and_electricity_usage.yml and gas_and_electricity_estimate.yml files into a local directory on your system. These files contain the Swagger API Description of the APIs that will be published in Apiary. They also contain mock data that's used as the service response.

  2. Open a browser window and go to Apiary:

    https://apiary.io/
  3. On the Apiary login page, provide your email address and password, and then click SIGN IN.

    Apiary login page
    Description of this image

    Note: You can also sign in by using your GitHub or Twitter account.

  4. The first time you log in to Apiary, enter energy as the name of your first API, and then click SAVE AND START USING APIARY.

    Name your API page
    Description of this image
  5. On the Editor page, replace the existing text with the contents of the gas_and_electricity_usage.yml Swagger file.

    Apiary Editor page
    Description of this image

    Note: The document is automatically validated.

  6. After the document is validated, click Save & Publish.

    Save & Publish
    Description of this image

    Note: If you have trouble saving and publishing the document, then verify that the text from step 5 is copied as it appears in the Swagger file.

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

    Inspector page
    Description of this image

    Note: The listening URL is just an API example. In later steps, verify that you use the generated URL of your API.

  8. On the Apiary page, create a new API for the estimate implementation by clicking Create New API.

    Name your API page
    Description of this image
  9. On the New API page, enterestimate in the New API name field, click Swagger, and then click Create API.

    Apiary Editor page
    Description of this image
  10. On the Editor page, replace the existing text with the contents of the gas_and_electricity_estimate.yml Swagger file.

    Apiary Editor page
    Description of this image

    Note: The document is automatically validated.

  11. After the document is validated, click Save & Publish.

    Save & Publish
    Description of this image

    Note: If you have trouble saving and publishing the document, then verify that the text from step 10 is copied as it appears in the Swagger file.

Creating an API in Oracle API Platform Cloud Service

In this section, you create an API in the API Platform Cloud Service Management Portal.

  1. Open a browser window and go to the API Platform Cloud Service Management Portal by entering the URL in this format:

    http://hostname.domain:port/apiplatform
  2. On the API Platform Cloud Management Portal login page, enter your user name and password, and then click Sign In.

    API Cloud Service Management Portal page
    Description of this image
  3. On the APIs tab, click Create API.

    APIs tab
    Description of this image
  4. On the Create API page, enter the following values, and then click Create:

    • Name: Energy
    • Version: 1
    Create API page
    Description of this image

Configuring Endpoints

In this section, you configure the two API endpoints that the requests and responses are sent to and received from.

Configuring the API Request

In this section, you configure the API request endpoint that users or applications send requests to for your API.

  1. On the APIs tab, click Energy, which is the API that's created.

    Energy API
    Description of this image
  2. On the API Implementation tab, in the API Request section, click Edit.

    API Implementation tab
    Description of this image
  3. On the Edit Policy page, click Next.

    Edit Policy page
    Description of this image
  4. On the Edit Policy page, select HTTP from the Protocol list, enter energy/1 in the API Endpoint URL field, and then click Apply.

    Edit Policy page
    Description of this image

Configuring the Service Request

In this section, you configure the service request endpoint that your back-end service receives authorized requests from. When a request meets all policy conditions, the gateway routes the request to this URL and calls your service.

  1. On the API Implementation tab, in the Service Request section, click Edit Policy Details.

    API Implementation tab
    Description of this image
  2. On the Edit Policy page, click Next.

    Edit Policy page
    Description of this image
  3. On the Edit Policy page, enter your API's URL from Apiary, select Use Gateway Node Proxy, and then click Apply.

    Edit Policy page
    Description of this image
  4. On the APIs tab, click Save Changes.

    Save
    Description of this image

Deploying Your API to a Gateway

  1. On the Deployments tab, click Deploy API.

    Deployments page
    Description of this image
  2. On the Deploy API page, select the gateway where you want to deploy your API, and then click Deploy.

    Deploy API page
    Description of this image

    The API deployment appears on the Waiting tab and is in the WAITING deployment state.

    Waiting tab
    Description of this image
  3. On the Deployments tab, verify that the runtime state appears as ACTIVE before testing your API.

    Deployed tab
    Description of this image

    Note: If the deployment isn't moved to the Deployed tab, then refresh the page.

Invoking Your API at Runtime

In this section, you learn how to invoke your deployed API by using Postman to interact with your APIs. You can also use any other REST client to invoke your API.

  1. Build your API's URL using this format:

    http://hostname.domain:port/api_endpoint_url/resource_path
  2. Open the Postman client, select the GET method, enter the API's URL, and then click Send.

    Postman client
    Description of this image
  3. On the Body tab, verify that the response was retrieved from your API in JSON format.

    Body tab with API response
    Description of this image

Want to Learn More?