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.

To illustrate API resources, we can use a (very simplified) example drawn from Apigee's own Developer Services API. The following snippet of WADL defines two API resources, /developers and /apps. For each API resource, it defines two methods, create and list.

<resource path="/developers">
  <method id="createDeveloper" name="POST">
  <method id="listDevelopers" name="GET">
<resource path="/apps">
  <method id="createApp" name="POST">
  <method id="listApps" name="GET">

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:

  • Collect fine-grained metrics for Analytics Services






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>


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



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.



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>

Modeling hierarchical URIs





This path applies equally to the following two URIs:






will resolve these hierarchical URIs as API resources appropriately.


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.



Help or comments?

  • Something's not working: See Apigee Support
    (Incorrect? Unclear? Broken link? Typo?)