Add APIs

Was this helpful?

When you add an API to the Apigee API Platform,  it generates a proxy for an existing backend service that you specify. You only need to provide the network address for the backend service, along with some information that the API Platform uses to model the API exposed to developers. The API proxy decouples your public interface from your backend service, shielding developers from back-end changes. As you make changes to back-end services, developers, insulated from those changes, continue to call the API uninterrupted.

The API Platform offloads many common management concerns from your back-end services. Once you've set up an API proxy its behavior can be configured using polices. These policies let you add functionality such as security, rate-limiting, content mediation, response caching, or customize behavior implemented using JavaScript and Python.

You can use the platform's API Analytics to see detailed metrics about how your API is consumed and performs.

An API proxy has three basic components: Backend Service URL, API Proxy URL, and API resources.

Backend Service URL

The network address of the backend service to which the API platform will forward request messages. 

API Proxy URL

(also known as a base path): The network address that developers call to invoke your API proxy. The root URL is partially generated by the API Platform. The generated domain has the following structure:

{myorg}-{environment}.apigee.net. 

where:

  • The{myorg}portion of the domain is the name of your organization in the API Platform. 
  • The {env} parameter reflects the name of the environment. By default your organization is provisioned with two environments, named test and prod. Thus a single API is provisioned with two domains:
    • {myorg}-test.apigee.net
    • {myorg}-prod.apigee.net

Note: You can use your own domain by configuring DNS for your Apigee account (if you're an Apigee Enterprise customer you can contact Apigee Support to set this up, otherwise try the process described in this FAQ).

You also define an additional URI fragment that uniquely identifies the API proxy within your organization. For example, you might define a URI such as /v1/weather. The resulting network address for the API proxy would be:

{myorg}-{environment}.apigee.net/v1/weather

API resources

Optional URI fragments that define RESTful resources exposed by your API proxy. A RESTful API is defined by a set of URIs that specify  'resources'. For example if your service backend provides weather reports and weather forecasts, you might define two API resources: /reports and /forecasts. If you have a structured document that defines your service interface, such as Web Application Description (WADL), you should refer to WADL for the definition of resources.

The API you define could involve only a single URL referring to a single resource:

{myorg}-{environment}.apigee.net/v1/weather

The API could define a set of URLs referring to a set of resources of the same type:

{myorg}-{environment}.apigee.net/v1/weather
{myorg}-{environment}.apigee.net/v1/news

The API could also define a of URLs referring to resources of different types:

{myorg}-{environment}.apigee.net/v1/weather/report
{myorg}-{environment}.apigee.net/v1/weather/forecast
{myorg}-{environment}.apigee.net/v1/news/local
{myorg}-{environment}.apigee.net/v1/news/international

You can further refine resource definitions by specifying the HTTP verb associated with a call: 

For example, you can optionally add the resource with GET and POST verbs specified:

GET {myorg}-{environment}.apigee.net/v1/weather/report

POST {myorg}-{environment}.apigee.net/v1/weather/report

The benefit of defining API resources is that you gain the ability to apply policies to requests that invoke those specific URIs, providing granular control over the data and services that your API proxy exposes. Additionally, the API Platform collects operation metrics specific to the API resources you define. By defining specific API resources, you gain the visibility required to identify performance bottlenecks or error conditions as they affect specific calls against your API. 

Back to top

Setting server information for your API

When you add a new API, you specify the URL of the backend service and the desired URI path that apps will use to invoke this API's proxy. The API proxy URL is the public face of your API, used by developers to invoke your API. The server URL is the private source of data, used by the API Platform to forward requests and return data to apps.

The server URL typically represents an API or service available via HTTP over the Internet (although the service may be exposed over a different protocol, with some other network interface). The API or service can be under your control (for example, an internal HR application or a Rails application you host in the Cloud) or it can be a third-party API or service (for example, Twitter or Instagram). Part of the fun behind using the API Platform lies in taking other people's APIs and customizing them to your own purposes. Of course, some form of authentication is usually required for such calls. The API Platform provides support for secure invocation of backend services via SSL-based mutual authentication, OAuth authorization, etc. (Refer to the Developer Guide for instructions.)

To add an API

  1. On the API tab, click the (+) icon.
  2. Enter a descriptive name for your API as the API Display Name.
    You can use your brand name so developers can easily identify your organization as the API provider. It's also a good idea to add a version to your API, such as V1.
  3. Enter the desired URI to the API Proxy URL.
    An example is /v1/api-example. (Custom domains can be configuring for your Apigee account (if you're an Apigee Enterprise customer you can contact Apigee Support to set this up, or refer to the process described in this FAQ).
  4. Enter the network address to which the API Platform directs app requests.
  5. An example is http://www.example.com.
  6. Optionally, add API  resources and HTTP verbs. You can do this later, and it is often an iterative process as you need increasingly granular control and visibility into your API.
    See Adding API resources for more information.
  7. Click Done. The API Platform generates an API facade and deploys that API facade to the 'test' environment in organization. Your API is immediately available to be invoked at the 'Root URL' you defined. 
Back to top

API versions

An API version is the version of the API that is exposed to an app developer. The version is usually embedded in the API facade path. For example, pivotaltracker.com/v3/services is version 3 of the pivotal tracker interface. The version rarely changes as it's part of the base path that developers include in their applications. The more often you modify the version, the more likely you are to frustrate the developers who have adopted it. Although it's not required, it a good idea to include a version when you set up a URL path for your API facade.

Back to top

Adding API resources

Adding resources is completely optional. Given the appropriate server URL, the API platform can correctly route incoming requests to your API without requiring that every resource be configured. However, if you do define resources you'll be able to:

  • Apply policies and scripted behavior to individual resource paths
  • Collect more detailed metrics for Analytics

The URL for each resource in an API starts with the root URL. So if the API is example, its root URL could be /v1/example_service and all its resources are subdomains of example_service. If example_service offered access to various forms of content like blogs, videos, news articles, and so on, it would be set up like this:

apigee-demo-prod.apigee.net/v1/example_service/blogs/
apigee-demo-prod.apigee.net/v1/example_service/videos/
apigee-demo-prod.apigee.net/v1/example_service/articles/

In a RESTful API, resources are typically named as plural nouns.

For a discussion of best practices when designing your base URLs and resources, see RESTful API Design: nouns are good, verbs are bad. Developers interact with the resources using the Hypertext Transfer Protocol (HTTP), and specifically using the HTTP verbs GET, POST, PUT, and DELETE. (There are more HTTP verbs, but they are used infrequently in APIs.)

Resources can be used to control access to specific assets or objects in your API. If you disable a resource, you are effectively blocking all the apps that call that resource from accessing an asset. You might want to do this if you need to disable a resource that is causing issues or is no longer supported.

A note on the term resource

We use the term resource as it is used in the Web Application Description Language (WADL) specification. (Note that this is just for convenience, and doesn't necessarily imply any endorsement of WADL.) According to WADL, a RESTful API consists of a base path and any number of resource paths. Resources are sometimes called API methods, but the term method can become overloaded, because a RESTful API also has associated HTTP verbs (GET, PUT, POST, DELETE) which are also sometimes called methods.

Resource path

The resource path is the URI for a specific resource. The location might require additional parameters to call a specific resource. For example, a resource for projects could carry the additional resource <projectID>, which would call a specific project in your database. If you need to add parameters to your resource path, use the format rootURL/resources/*/resource where the asterisk ( * ) indicates a required parameter. For example:

http://apigee-demo-prod.apigee.net/v1/example_services/blogs/myblog/stories

HTTP verb

As with resources, configuring HTTP verbs is optional, and is used when you require more granular control over your API (for example, you want to apply a script to the POST verb, but not to the GET.) Note that you aren't really adding a verb to the resource because (with RESTful services) the verbs are there already; you're just attaching verb-specific conditions.

To add resources

You can add resources when you're adding the API for the first time, or you can add them later on. (In fact, a typical approach is to iteratively specify resources, verbs, and parameters as your management requirements become more targeted.)

  1. In the Add API dialog, select a verb: ALL (includes all verbs in this list), GET, POST, PUT, or DELETE.
  2. Enter the resource path in the Path field.
  3. Enter a human-readable name that describes the resource, such as blogs, videos, or articles, as the Display Name.
  4. Enter a Description of the resource.
  5. Click Add Resource until all resources are added, then click Done.
Back to top

API revisions

Unlike API interface versions, you can revise a single API many times. Whenever you update your API by adding a new policy or reconfiguring an existing one, the API Platform generates a new revision. Revisions are an internal mechanism used by the platform to track the latest edits you make to your API. They are mainly used to manage deployments, and to rollback to previous revisions as necessary.

Usually, you define your APIs iteratively. The first revision is often fairly general, and lets you to learn how your API performs, how various apps invoke it, and what specific problem patterns begin to emerge. By incrementally adding to the detail of the representation of your API, you gradually increase your visibility and your fine-grained control over how your APIs behave.

The API revisions table displays a history of the revisions for the API and shows which are deployed in production and non-production environments. You can deploy multiple revisions of an API. It's common to have a revision in production while another revision is in non-production as it's being tested or developed.

You can edit an API offline by downloading the current API revision file and then uploading your changes. Refer to the API Platform Developer Guide for instructions.

To deploy an API revision

Depending on your role, you may not be able to deploy to all environments. Users can only deploy to test environment. If you're an administrator you can deploy to any environment, including 'prod'.

  1. In the API revision summary, roll over the Deployment Status column for the revision you want to deploy and click the Deploy icon.
  2. Confirm the deployment. Deployed revisions are indicated in green.

Downloading and uploading revisions

You can choose to edit your API offline by downloading the proxy files and uploading them back to the API Platform when you're done. See Edit API revisions offline

See also

Back to top