A developer builds an app that makes requests to your APIs to access your backend services. The following image shows the relationship of a developer to an app and to an API:
Publishing is the process of making your APIs available to app developers for consumption. Apigee supports a flexible publishing model that gives you complete control over the publishing process.
Video: Check out this short video for an introduction to API publishing.
Publishing APIs can be broadly defined by the following tasks:
- Create the API products on Edge that bundle your APIs.
- Register app developers on Edge.
- Register apps on Edge.
- Provide documentation and community support for your APIs, including:
- API reference documentation
- Examples and tutorials
- Forums, blogs, and other features to foster the developer community
Video: Check out this short video to learn how to publish APIs on the portal.
The first task in publishing is to create an API product. An API product is a collection of API resources that are offered as a package to app developers for consumption. Create API products by using the Edge management API or UI.
In this figure, your API consists of two products, each containing three API resources.
As an API provider, you are responsible for building the APIs and API products to handle access control, usage restrictions, and any other business requirements. For example, you might:
- Release a free API product that allows read-only access to its API resources.
- Release a second API product for a low price that allows read/write access to the same API resources as the free version but with a low access limit, such as 1000 requests per day.
- Release a third API product for a higher price that allows read/write access the the same API resource but with a high access limit.
The important thing to remember is that Edge give you the flexibility to create API products that match the business requirements of your APIs.
For more information on creating API products, see Creating API products.
A developer creates the apps that consume your APIs. Developers must be registered on Apigee Edge before they can register an app and receive an API key.
Through the app registration process, you control who has access to your APIs. At any time, you can delete an app developer, which invalidates all API keys associated with that developer, therefore denying that developer access to your APIs.
As an API provider, you decide how to register developers. For example, you can use a manual registration process that requires a potential developer to contact your organization to register. The potential developer must supply all necessary information, such as an email address, first and last name, and company name. If you approve the developer’s request, you can use the Edge management UI to manually register the developer. See Adding developers to your organization for more.
Apigee also provides tools that you can use to automate the developer registration process. For example:
- Use the Apigee Edge management API to integrate registration functionality into your existing website. The Edge management API is a REST API that you can use to perform all aspects of the developer registration process. See Using the Edge management API to Publish APIs for more.
- Use the Apigee Developer Services portal to register developers. The portal has built-in support for developer registration, but also has many other features to support your APIs. See What is a developer portal? for more.
Before an app can access your APIs, the app must be registered on Edge. However, only a registered developer can register an app on Edge.
At the time of app registration, the developer selects one or more API products. For example, you might publish multiple API products corresponding to different types of services and pricing plans. The app developer can then pick and choose from the list of available API products.
Edge does not require that you to let the developer associate multiple API products with an app. Your publishing plan can be structured such that the developer can select only a single API product. Or, you can automatically assign a default API product to all apps so that the developer does not even get to choose one.
In response to registering the app on Edge, Edge assigns a unique API key to the app. The app must pass that API key as part of every request to an API resource. The key is authenticated and, if valid, the request is granted. At any time, you as the service provider can revoke the key so that the app can no longer access your APIs.
As an API provider, you decide how you want to register apps. You could:
- Use a manual process that requires a developer to contact your organization to register their app. In response, you would send the developer the API key, possibly by email.
- Use the Edge management API to integrate app registration functionality and key delivery into your website.
- For a paid Edge account, use the Apigee Developer Services portal which has built in support for app registration and API key delivery.
As a best practice, there is a 1-1 correlation between the app that the developer registers on Edge and the actual client app that they build. However, this correlation is not enforced by Edge. For example, a developer registers a single app on Edge, associated that app with an API product, and receives back an API key. The developer is free to use the API key from any client app.
For more information, see Registering apps.
An important consideration for publishing API products is providing documentation and a developer feedback mechanism. Developer portals with social publishing features are increasingly being used for communication with the development community. This includes communicating static content, such as API documentation and terms-of-use, as well as dynamic community-contributed content such as blogs and forums, as well as customer support features.
You can build your own website to deploy your documentation or, if you have a paid Edge account, you can use the Apigee Developer Services portal. The portal has built-in support for documentation, blogs, forums, and other types of content required to support your developer community.
You can use the Apigee Console to document your APIs, and incorporate the console into your portal. The console is an interactive GUI that lets developers make requests to your API without having to write any code. You can use the Console to set request, header, and body parameters, view the request and response content, and pass authentication credentials to the API.
For more information, see What's an API Console?.
SmartDocs lets you document your APIs on the Developer Services portal in a way that makes the API documentation fully interactive. Interactive documentation with SmartDocs means portal users can:
- Read about the API
- Send a live request to the API
- View a live response returned from the API
For example, the following figure shows an API documented on the portal by using SmartDocs. This API provides weather information for a specific location:
The developer enters a value for the 'w' query parameter to specify the location, and then clicks the Send the request button to see the live request and response. By creating an interactive documentation on your APIs, you make it easy for portal user to learn, test, and evaluate your APIs.
The Edge management API is a REST API that enables you to access API Services using any HTTP client. Apigee uses SmartDocs to create interactive documentation for the Edge management API. See that API documentation here.
For more information, see Using SmartDocs Beta to document APIs.