Was this helpful?

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>
  <method id="listDevelopers" name="GET">
  </method>
</resource>
<resource path="/apps">
  <method id="createApp" name="POST">
  </method>
  <method id="listApps" name="GET">
  </method>
</resource>

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>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath &quot;/apps&quot;)</Condition>
</Flow>

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 Flow configurations.)

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

http://{org_name}-test.apigee.net/{proxy_path}/apps

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>
    <Request/>
    <Response/>
    <Condition>(proxy.pathsuffix MatchesPath &quot;/apps&quot;) and (request.verb = &quot;POST&quot;)</Condition>
</Flow>

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:

/developers/{developer_email}/apps

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

/genus/:id/species

This path applies equally to the following two URIs:

/genus/18904/species
/genus/17908/species

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

/developers/*/apps

and

/genus/*/species

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:
/developers/**

That API resource will resolve the following URI paths:

/developers/{developer_email}/apps
/developers/{developer_email}/keys
/developers/{developer_email}/apps/{app_id}/keys

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.

 

コメントを追加

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.