Coordinating API and App development cycles

4 2 3,960

Overview

API proxies don't live in isolation, they are intimately linked to the Apps that consume them and the Target APIs they in turn consume. Thinking about how you coordinate the SDLC of you API and Apps is important to ensure clear path to production for both proxies and Apps.

There are many different factors to consider but in order to constrain the scope of this article I'm going to assume that we're set up on an Edge cloud instance.

Edge Set Up

The following is a standard setup that we advise most customers to follow for API proxy development.

Proxy changes are promoted through the different environments (hopefully using Continuous Integration) and the different kinds of testing required can be performed in each environment as the proxy gets closer to go live.

This is assuming the Target systems have the appropriate numbers of environments to support this model. If the Target system has less environments then you may choose to reduce the numbers of Edge environments or point a number of different Edge environments to the same Target environment.

The environments are split across two orgs to allow administrative separation of the environments i.e. typically you'll have different set (or at least a subset) of org admins in the production org vs the org admins in the non prod org.

Edge EnvironmentTargetType of TestingApigee Org
DEVMockData and BehviourNon Prod
TESTTESTIntegrationNon Prod
PERFTEST / PERFPerformanceNon Prod
UATUATSmokeNon Prod
PREPRODSmokeProd
PRODPRODSmokeProd

Your API development cycle may not need all these stages but it's a good starting point.

See https://community.apigee.com/answers/22893/view.html for more details on why we advocate this approach.

Developer Portal Setup

The Developer Portal is the main route by which App developers will interact with your API proxies and associated documentation. A well maintained and easy to use Developer Portal is key to a good developer experience and keeping your API program as self service as possible.

The standard Apigee cloud setup provides live, test and dev Developer Portals.

App Developers

Let's consider what kind of App developers you might be working with as this will dictate the types of testing they will need to perform and in turn the kinds of environments you'll need to provide to them.

In the next few sections I'll be talking about releases of the API as opposed to versions of the API to try to avoid any confusion around API versioning v.s. API release cycles. For the sake of argument let's assume that all API versions discussed below are v1 in an API versioning sense unless explicitally stated otherwise. See https://community.apigee.com/questions/21913/is-rest-apis-versioning-necessary.html for a wider discussion.

External Partners / Internal Teams

Many API teams work closely with selected external partners or internal teams to build Apps to consume their APIs. Typically these kind of teams require a more collaborative approach to testing where App development will be against the next release of the API that's in development. So if we consider the release of the API in production to be 1.0 the API development team might have release 1.1 available for the App developers to build against.

API and App development is ideally not tightly coupled together. As long as App development does not require any of the new functionality available in release 1.1 then App development should be able to be done against release 1.1 and App developers should have high confidence that this should work in production OK even if they go live before API release 1.1 is pushed out since API release 1.1 should be backwards compatible. Any backwards incompatible changes in a release would require a change the in the API version. Let's call this App Integration Testing.

Before go live there may be the requirement to do a final test against a pre production environment which contains exactly the same release of the API as production but against a non production target. Let's call this App Sandbox Testing. As discussed above this should not be required as an App developed v.s. the 1.1 release of the API should work v.s. release 1.0 unless it requires additional functionality in release 1.1.

Obviously if the new App being developed needs functionality in release 1.1 the release of the App will need to be coordinated with the API release.

External Developers

If you have public APIs or an open developer program with many App developers consuming your APIs them it's likely you will not want to try and coordinate any kind of release planning around your APIs with their App development lifecycles.

The most pragmatic approach to this is that they develop against the same release of the API that exists in production. This is the same as the App Sandbox Testing scenario discussed above. The main point here is that you're not trying to coordinate App and API release cycles for potentially large groups of External App Developers.

App Testing

In order to support the two main kinds of App testing outlined above and App go lives there's a number of different approaches.

One Developer Portal or Two?

Each Developer Portal environment (dev, test and live) can point to only one Edge Org. Above we explained why it's recommended to split the Edge environments into two Orgs to provide administrative separation (prod and non prod) but this means that we need to choose which Edge org to point to.

Two developer portals

If we chose to expose the live and test versions of the Developer Portal externally we can point each one at a different org. e.g. the live Developer Portal points to the prod Edge Org and the test Developer Portal points to the non prod Edge Org.

PROs:

Separates App developer access into two different orgs which allows

  • Separation of Analytics
  • Separate production and nonproduction API Products exposed in different places

For example in the test Developer Portal you could expose Products supporting App Integration Testing (e.g. APIs in UAT)

In either the test or live Dev Portal you could expose Products supporting App Sandbox Testing. How this is exposed will depend on your API development cycle. If you need all 6 environments outlined above for the API's path to production then ideally you need an alternative place to deploy APIs for App Sandbox Testing where the API release matches production but is pointing to a non production target. You may be able to use the Edge PRE environment for this purpose.

I'll discuss options for creating additional pseudo environments at the end of this article.

In the live portal App Developers can create their production Apps and associated them with Production Products i.e. APIs in the Edge PROD environment.

CONs:

You need to maintain two Developer portals and decide what content is presented in the two portals.

Do you want to maintain Blogs, FAQ and Forums in two places or maybe disable those features in one version and have all this kind of content in just one place? Different programs will have differing priorities and bandwidth which will dictate the direction taken.

App Developers will need to log into two different places depending on whether they are trying to access information about the live or 1.1 release of the API.

Technical API documentation (typically using SmartDocs) is less of an issue since the SmartDocs in the environment should reflect the release of the API currently deployed in that environment.

One Developer Portal

We can choose to just expose the live version of the Developer Portal then we need to choose which Org the Dev Portal points to.

PROs:

Only one place for App Developers to visit and only one place to maintain documentation.

CONs:

Only one Org can be exposed and this means you need to decide which of the following approaches to take

One Developer Portal - Testing Apps only

In this scenario the live version of the Dev Portal points to the Non Prod Edge Org

When App developers first register they can create an App and choose to associate this with one or more Products. These products will represent APIs in the Non Prod Edge Org.

If you need to support App Integration Testing then one of the Products exposed should provide access to release 1.1 of the API e.g. exposing APIs from the UAT Edge environment.

If you need to support App Sandbox Testing then one of the Products exposed should provide access to release 1.0 of the API but pointing to a non prod target i.e. the same release as currently in production. As discussed above, depending on your API development lifecycle you many not have a 'spare' environment to support this and I'll discuss options later in the article.

CONs:

When an App developer wants to go live they cannot sign up for a Product that exposes APIs in the Production Org as this developer portal only points to the Non Prod Org.

This means that at Go Live Apps and their association to Products will need to be done manually on the Edge side and the credentials securely passed to the App developer.

An alternative approach would be to create a separate route for Developers creating and retrieving their prod credentials outside the Dev Portal. Creating and managing Apps can all be driven by management API calls so you could orchestrate this in a separate App of your own.

One Developer Portal - Production Apps only

In this scenario the live version of the Dev Portal points to the Prod Edge Org

When App developers first register they can create an App and choose to associate this with one or more Products. These products will represent APIs in the Prod Edge Org.

This makes it simple for App Developers to create their production Apps and associate them with Production Products. You could choose to not expose them initially e.g. make them private Products.

The process for exposing the Sandbox or Integration Products needs some thought. If you need to support App Integration Testing then one of the Products exposed should provide access to release 1.1 of the API. This typically would need a separate pseudo environment with the 1.1 release of the API.

If you need to support App Sandbox Testing then one of the Products exposed should provide access to release 1.0 of the API but pointing to a non prod target i.e. the same release as currently in production. This might be supported by the PRE environment if it's not required as part of the API development cycle but may need an additional pseudo environment to support this.

Alternatively you could chose not to expose the Integration or Sandbox functionality in the Dev Portal and manage Non Prod Apps in the Non Prod Org and communicate the credentials to App developers out of band. This could either be a manual process or via an API leveraging the management APIs as mentioned above.

Pseudo Environments / exposing more revisions of your API

Some of the approaches above may mean you don't feel you have enough environments to separate out / support the API and App Development lifecycles. The work around for that would be to deploy multiple revisions of a given API into the same environment either with different base paths or under different vHosts. This allows you to effectively expose more revisions of your API to suit the needs of your ecosystem.

Summary

Coordinating API and App development to make the overall process as smooth as possible is key to building a successful API program. Think about the needs or your API developers, App Developers and realities of your target systems when deciding how to set up your Edge and Developer Portal environments.

There lots of options outlined above that may seem overwhelming at first but focus on keeping it simple and addressing your current needs and you have all the tools you need.

If you have any comments or questions on this article please add them below or get involved in the discussion here - https://community.apigee.com/questions/23339/how-do-you-coordinate-your-api-and-app-development.html

Comments
jonesfloyd
Staff

Nice article, @Dom Couldwell!

Marsh
Staff

It may be worth pointing out that the environments for the classic Drupal-based developer portal exist to support an SDLC of the portal itself, since customers have the ability to modify the source code. Having three environments means code-level changes can migrate from dev through test to live. It could possibly map to corresponding API environments, though that's not the original intent, and there might be some nuance to how the portal's content, which isn't really part of the SDLC, moves, too.

Our new portals are a bit different. Since it isn't possible to modify their source code directly, there isn't the same need for SDLC. Also, since they are self-service and lightweight, it is easy to spin up a new portal on demand, for example you wanted to experiment with a drastically different information architecture or even just to play with styling the portal differently. We're currently considering ways in which new portals could map to different API environments as well, so if you have thoughts on this, I'd love to hear them!

Version history
Last update:
‎04-28-2016 01:27 AM
Updated by: