Was this Helpful?

Introduction

You develop on Apigee Edge by using:

  • The Edge management UI: A browser-based management user interface
  • The Edge management API: A RESTful API that supports XML and JSON

After you become familiar with the Edge development environment, download and try the samples. For more information, see Using the sample API proxies.

Using the Edge management UI

The Edge management UI simplifies many interactions with Edge in the context of a browser-based tool. In the Edge management UI, you can:

  • Create API proxies
  • Create API products
  • Manage developers, apps, and other parts of your organization
  • Configure your test and production environments
  • Access the Console
  • Access App Services
  • Implement JavaScript and Node.js applications
  • and much more

Video: Check out this short video for a quick tour of the Edge management UI.

Using the Edge management API

The Edge management API is a RESTful API that enables you to access API Services using any HTTP client. The Edge management API enables programmatic scripting to perform development tasks, such as deployment of API proxies. The RESTful API also provides access to low-level capabilities that are not exposed by the management UI for reasons of usability. The Edge management API is designed to be lightweight and to impose few restrictions on the client code that consumes it.

As a RESTful API, the Edge management API, follows a pattern in which capabilities are exposed as API 'resources'. API 'resource' is a term derived from the web application description language (WADL) specification. According to the WADL specification, a RESTful application can be described as a set of resources.

Each resource, in turn, defines a set of methods that act on it.  Some examples of the resources exposed by the Edge management API are API proxies, API products, apps, and developers. For a complete list of resources and methods, see the API reference.

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

Your organization name is used in the base path for the requests to the Edge management API. You can locate your organization name under User Settings in the Edge management UI. For example, if your organization name is 'apibuilders', then every call that you make to the 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 segregated according to environments. Two environments are provided by default: test and prod. An example of a resource that is scoped by environment is Cache. A default Cache, called 'mycache' is set up 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

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

To consume the Edge management API you require an HTTP client. 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:

  • myname: The username for your Apigee account
  • mypass: The password for your account in an Apigee account
  • myorg: The name of your organization

Note: 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 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 myname:mypass

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 that have a Content-Length of at least 1024 bytes. Use 'Accept-Encoding: gzip, deflate' in a cURL command.

Example: making call to 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 myname:mypass

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 myname:mypass -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 myname:mypass -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

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)