Send Docs Feedback

Note: Most user interface tasks can be performed in Edge Classic or the New Edge experience. For an overview, getting started topics, and release notes specific to the New Edge experience, see the docs.

Developing with Apigee Edge

As a service provider, you develop APIs for consumption by client apps. You can use two different development methods to create, configure, and maintain API proxies and API products:

To get started with either method, you first must create a free account at https://accounts.apigee.com/accounts/sign_up. See Using the Apigee Edge development environment for more.

Client app developers access your services by making HTTP requests to your API proxies. There are no requirements on the type of client app, other than making a properly formatted HTTP request and handling data returned by the response.

If client app developers want to take advantage of the app-building features included with Edge API Services, their apps can make HTTP requests directly to those services.

Using the management UI

The Edge management UI is a browser-based tool you can use to create, configure, and manage API proxies and API products. There are a few tasks that require you to use the management API, though.

For an introductory tutorial using the management UI, see Create your first API proxy.

In the Edge management UI, you can:

  • Create API proxies by editing code and tracing flow of requests through your proxies.
  • Create API products that bundle proxies for exposure to client requests.
  • Manage developers and developer apps.
  • Configure your test and production environments.
  • Implement JavaScript and Node.js applications.

The following image shows the Edge management UI that you can use to create and configure an API proxy:

Using the RESTful management API

You can use Apigee Edge RESTful management APIs to create, configure, and manage API proxies and API products, policies for logic in your API proxies, apps and app developers, caches. The management API also provides access to low-level capabilities that are not exposed by the management UI for reasons of usability.

These API endpoints often take data containing configuration information and require you to pass authentication information, such as username and password, to access them. Following RESTful principles, you can call HTTP GET, POST, PUT, and DELETE methods on any of the API resources.

The following example uses cURL to execute an HTTP POST request to create an API product with Create API Product:

$ curl -H "Content-Type:application/json" -X POST -d
'{
  "approvalType": "auto",
  "displayName": "Free API Product",
  "name": "weather_free",
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ]
}'
https://enterprise.apigee.com/v1/o/my_org/apiproducts -u email:password

For a complete list of resources and methods, see the API reference.

As in other RESTful APIs, the Edge management API exposes capabilities as API resources. Each resource defines a set of methods that act on it.

Following RESTful principles, you can call HTTP GET, POST, PUT, and DELETE methods on any of the API resources.

  • GET: Retrieves a list of resources, or the profile of a specific resource.
  • POST: Creates a resource, or passed in a parameter, performed an action on resource. For example, when you revoke OAuth access tokens, you use the POST method along with the parameter action=revoke.
  • PUT: Updates an existing resource.
  • DELETE: Deletes an existing resource.

Understanding the base path

The path you'll use in management API requests concatenates the following:

  • A base path that includes your organization name. (You can locate your organization name under User Settings in the Edge management UI.)
  • An endpoint that points to the Edge resource you're accessing.

For example, if your organization name is "apibuilders", then every call you make to the management API will use the following base path:

https://api.enterprise.apigee.com/v1/organizations/apibuilders

To retrieve a list of API proxies in your organization, you would call GET on:

https://api.enterprise.apigee.com/v1/organizations/apibuilders/apis

Many resources are scoped by environment. Two environments are provided by default: test and prod. For example, caches are scoped by environment. A shared cache called "mycache" is included by default in every environment.

You can list caches by calling GET on the cache resource as follows:

https://api.enterprise.apigee.com/v1/organizations/apibuilders/environments/test/caches
https://api.enterprise.apigee.com/v1/organizations/apibuilders/environments/prod/caches

Passing credentials

The API enforces HTTP Basic Authentication. You always need to pass in your username and password for your account. These can be passed in as a Base64 encoded header, or as parameters (as demonstrated below) in an HTTP client. The following is an example of an HTTP Basic Authentication header:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Running cURL commands

Use an HTTP client to make requests to the management API. Many examples in the documentation provide sample API requests using cURL, a widely-used HTTP client. If you need to install cURL, you can download it from http://curl.haxx.se.

If you cut and paste a cURL command from the doc to your terminal, you must replace the following variables in the command with information for your Apigee account:

  • email: The email for your Apigee account
  • password: The password for your Apigee account
  • myorg: The name of your Apigee organization
On Windows, make sure to download a version of cURL that includes the libcurl library. Also on Windows, you might need to use a flag to disable the trust check that cURL performs against the TLS/SSL certificate presented by the API Platform. You can do this by adding -k to each request you submit via cURL on the command line. This only disables the trust check and does not disable encryption. For example:
$ curl -k https://api.enterprise.apigee.com/v1/organizations/{org_name}/apis -u email:password

If you are using the Edge samples, set the values for your organization, username, and password in the file /setup/setenv.sh. Once you have done so, you can run the simplified deploy and invoke scripts provided for each sample API proxy. See Using the sample API proxies for more information.

Calls to the management API support gzip compression on responses. If you set 'Accept-Encoding: gzip, deflate' in your API calls, any response greater than 1024 bytes gets returned in gzip format.

Example: Making requests of the management API

In this example, you make an API call to Edge. The API call in this example returns a list of the names of all API proxies in your organization. Copy and paste the following command into the terminal window on your computer.

$ curl https://api.enterprise.apigee.com/v1/organizations/{org_name}/apis -u email:password

For brevity, you can abbreviate /organizations as /o. For example, if your username is me@mycompany.com, your password is secret, and your account in the organization called apifactory, then the request looks like this:

$ curl https://api.enterprise.apigee.com/v1/o/apifactory/apis -u me@mycompany.com:secret

The response should should contain a JSON array with two API proxies, which are created by default for all new users:

[ "oauth", "weatherapi" ]

cURL has a few tools that can make you life easier. For example, you often need to see the HTTP headers associated with a request. To obtain this detail about an HTTP request, you can use the -v flag provided by curl. For example:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis -u email:password -v

If you only want to see the HTTP headers on the response from the API Platform (and not the content), then you can use the -I flag.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apis -u email:password -I

Example: Returning XML

JSON is the default format for response messages. If you require XML, you can add an HTTP Accept header to get an XML response instead of JSON:

$ curl -H "Accept:text/xml" https://api.enterprise.apigee.com/v1/organizations/apifactory/apis -u me@mycompany.com:secret

When POSTing or PUTting payloads in XML, use the Content-type HTTP header:

$ curl -H "Content-type:text/xml" -X POST -d \
'<XMLPayload>
 </XMLPayload> ' \
https://api.enterprise.apigee.com/v1/organizations/apifactory/apis \
-u me@mycompany.com:secret

Deployment environments

Every organization using Apigee Edge by default has at least two environments they can use to develop, test, and deploy APIs: test and prod.  Use the test environment to develop and test your APIs before making them publicly available. Only your internal developers can access APIs deployed to the test environment. Deploy your APIs to the prod environment to make them publicly available to app developers.

Debugging and testing

Edge API Services provides a trace tool that lets you debug end-to-end request and response flows. The trace results display request and response headers and payloads, policy execution, variable values, and any errors that may have occurred during the flow.

Key data points for use in troubleshooting:

  • Timestamps: Use timestamps to see how long each step takes to execute. Comparing timestamps helps you isolate the policies that are taking the longest to execute that are slowing down your API calls.
  • Base path: By verifying the base path, you can ensure that a policy is routing the message to correct server.
  • Results of policy execution: These results let you see if the message is being altered as expected, such as if the message is being transformed from XML to JSON, or if the message is being cached.

The following figure shows trace results:

Each Trace session is broken down into the following major steps:

  • Original request received from client: Displays the verb and URI path of the request from the client app, headers, body data, and query parameters.
  • Request sent to your backend service: Displays the request message sent to the backend service by the API proxy.
  • Response returned by the backend service: Displays the response headers and payload returned by the backend service.
  • Final response sent to client: The response message returned to the requesting client app once the response flow has executed.

Help or comments?