The Apigee API enables you to create, configure, manage, and administer the RESTful resources exposed by Apigee.
The Apigee API is the same one used by Apigee user interface. You can even think of the Apigee Web UI as a reference implementation of the Apigee API (albeit an amazingly robust and full-featured one).
Often you can perform the same action in the UI as via the API. However, the API provides access to all capabilities of Apigee , and even lets you do some things a bit differently and more flexibly than the UI does, since the API is not constrained by the same UX needs as a human interface. It's important to be aware that you can do some things using the API that are not supported by the UI. Thus, some changes you make via the API may not be reflected in the UI.
In the long run, you’ll probably find that some mix of working in the UI and working via the API is most effective for you. The benefit of Apigee is that you can define and implement the workflow that suits your needs the best.
Prerequisites
The Apigee API is available over the Internet—any HTTP client is supported.
All you require is a user account within an Apigee organization. This provides the Basic Auth (username:password) credentials that you pass with each API call for authentication.
If you do not have an account, you can sign up for the trial here: http://enterprise.apigee.com/trial
The Apigee API Model
You can begin familiarizing yourself by using the Apigee API Console.
The following diagram displays the entity relationships in the Apigee API.
- Organization: Every Apigee account maps into an "organization." Assuming you're an administrator, you can add and remove users to and from your organization. If you are not an administrator, you are a user within your organization. This gives you the ability to log in to the Apigee UI for your organization. It also enables you to consume the Apigee API to access capabilities within your account. This is why you have to specify the organization in each API request you make.
- Company: An optional container for developers. Use the Company entity when you need to group developers under a single entity. This option used when you require billing information for a corporate entity which may or may not be managed by the developers who are building apps.
- Developer: A developer is a person who builds apps that consume the APIs managed in your organization. You can add, update, or remove developers within your organization. You can also group developers using "company" entities. Developers can be internal to your organization, they might be partners, or they can be external.
- App: A client application (e.g., an iOS or Android app) that is built by a developer and which consumes your API products.
- App family: An arbitrary grouping of apps. This is often used to enable the creation of an app family that contains two children: a sandbox instance of the app, and a production instance of the app. (Note: Apigee makes no assumptions about how you structure "Sandbox" and "Live" instances.)
- API product: A bundle of resources with an optional associated service plan and an OAuth scope. (We use "resource" to follow the WADL example—another common term is methods.) API products form the basis of access control with Apigee. They enable you to bundle your API resources into packages that are consumed by developers. You can have one API, and multiple API products configured on top of it, such as a "Free Introductory API Product" and a "Premium API Product."
- Environment: Every organization (including yours) is provisioned with two environments, one test and one prod. The naming is arbitrary—you can use these environments however you wish, and Apigee makes no assumptions about your SDLC requirements. You can deploy an API proxy to either environment. Typically you configure your API in the test environment, trace API calls and refine the API, and then deploy it to the prod environment for public consumption. (Note that the two environments have different URLs, which are defined as virtualhosts.
- Virtual host: The hosts which define the base URL for the APIs managed by Apigee. Every organization has one or more virtual hosts per environment. Usually, for each environment, you have one virtual host running on port 80 and another on port 443 to support SSL. To modify your virtual hosts, contact Apigee support.
- Key: Sometimes called a consumer key or an API key, this key is presented to Apigee at runtime by an app. The key is used to determine whether the app is allowed to access a particular resource. Note that keys belong to apps and have associated API products. Depending on how you configure your API product, keys can be approved manually or automatically.
- Access token: An OAuth construct addressed in the Apigee OAuth documentation.
- Authorization code: An OAuth construct addressed in the Apigee OAuth documentation.
What kinds of apps can I write against the Apigee API?
There are a few basic types of apps that you can build against the Apigee API:
- API provisioning and management: Import, deploy, configure, and manage API proxies to Apigee.
- Developer provisioning and management: Add developers and manage their profiles within your organization.
- App provisioning and management: Add apps, and control and monitor their access to your APIs.
- Analytics and insights: Monitor and analyze how your APIs are being consumed.
- Apigee account provisioning: You can integrate Apigee with your enterprise provisioning systems. APIs are available for adding, deleting, and managing users within your Apigee organization.
- Developer portal apps: Managing the front-end for your developer program by building apps that register developers, and that enable those developers to register their apps, obtain API keys, and get Analytics.
- Software development lifecycle apps: The core of the Apigee system are APIs which are managed by a proxy "facade." These proxies provide pipeline processing of the messages that flow to and from your APIs. API proxies are bundles of configurations and (sometimes scripts and code) and thus require a development process. The API enables you to implement apps or scripts that implement the SLDC best suited to your organization.
Tools
All you need to use the API is an account within the organization set up on Apigee.
The only tool you require is an HTTP client. For the purposes of this document, we rely on cURL, a command-line HTTP client. Feel free to use any HTTP client you prefer. Or simply use the Apigee console.
cURL is available here: http://curl.haxx.se/
Apigee also provides an optional deployment script (written in Python) to assist in importing and deploying APIs.
