Send Docs Feedback

API resources

Understanding API resources

RESTful services are collections of API resources. An API resource is a URI path fragment that identifies some entity that developers can access by calling your API. For example, if your service backend provides weather reports and weather forecasts, your API might define two API resources: /reports and /forecasts.

The term resource is used in the Web Application Description Language (WADL) specification. This is just for convenience. It 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.

Video: Check out this short video for an introduction to API resources.

Defining API resources

Defining API resources in an API proxy is completely optional. However, by defining API resources in an API proxy, you gain the ability to apply fine-grained management and monitoring.

You will be able to:

  • Apply management in way that reflects the semantics of your API model
  • Apply policies and scripted behavior to individual resource paths (URIs)
  • Collect fine-grained metrics for Analytics Services

For example, imagine that you need to apply different types of management to /developers than to /apps.

To do so, you add two API resources: /developers and /apps.

In the Develop view of the API proxy builder, select New > Resource.

In the Navigator menu, you can see that two Flows have been created: Apps and Developers.

Select one of the Flows to view the API resource configuration:

<Flow name="Apps">
    <Description>Apps registered in Developer Services</Description>
    <Condition>(proxy.pathsuffix MatchesPath &quot;/apps&quot;)</Condition>

As you can see, API resources are simply conditional Flows that evaluate the URI path of the inbound request. (The proxy.pathsuffix variable identifies the URI of the request that follows the BasePath configured in the ProxyEndpoint configuration.)

Each API resource that you define is implemented by a conditional Flow in the API proxy. (See Flows.)

Once you deploy the API proxy to the test environment, the following request:


will cause the condition to evaluate to true, and this Flow, along with any associated Policies, will execute.

If you have a WADL for your API, create an API resource for each resource in the WADL. This will enable you to configure fine-grained management over your API.

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

For example you may need to treat the "create app" method differently than "list apps". To do so, specify the HTTP verb associated with the API resource. In this example, you need to manage the Create App method, so select the POST method.

Select Add.

Adding this API resource results in a new Flow. The new Flow is added to the ProxyEndpoint for the API proxy that you are building. If you look at the ProxyEndpoint configuration, you will see that the following Flow configuration has been added:

<Flow name="CreateApp">
    <Description>Creates an app</Description>
    <Condition>(proxy.pathsuffix MatchesPath &quot;/apps&quot;) and (request.verb = &quot;POST&quot;)</Condition>

Modeling hierarchical URIs

In some cases, you will have hierarchical API resources. For example, the Developer Services API provides a method for listing all apps that belong to a developer. The URI path is:


You may have resources where a unique ID is generated for each entity in a collection, which is sometimes annotated as follows:


This path applies equally to the following two URIs:


To represent this structure in an API resource, you can use wildcards. For example:




will resolve these hierarchical URIs as API resources appropriately.

In some cases, especially for deeply hierarchical APIs, you may simply want to resolve everything below a certain URI fragment. To do so, use a double asterisk wildcard in your resource defintiion. For example, if you define the following API resource:

That API resource will resolve the following URI paths:


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, Apigee Edge 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.

Resources can be used to control access to specific assets or objects in your API. If you disable an API resource, or if you add a security policy to it, you are effectively blocking all the apps that call that resource.

For a discussion of best practices when designing your base URLs and resources, see RESTful API Design: nouns are good, verbs are bad.


Help or comments?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click Send Docs Feedback on this page.
    (Incorrect? Unclear? Broken link? Typo?)