API Planing


API Planing should take place before you perform you API Development

The planning phase ensures that the right APIs are built, the right way. This involves portfolio planning, API modeling, business justification, and other aspects common to traditional SOA governance practice.

For consumer APIs, the planning phase is not as critical as it is for enterprise APIs. Most consumer APIs are market driven, so distribution and agility are more important than reuse and scalability. Also, for Public APIs it is more important to be able to "experiment quickly and fail cheaply." Thus, business planning is more important than IT planning.

For Internal APIs and Partner APIs require more planning since they are tied to back-end transaction systems that are highly protected or secured. These APIs carry Financial and Regulatory Risk liabilities, must be carefully planned, and must remain as functionally stable as possible over long periods of time. Much of the traditional SOA planning disciplines and technologies apply directly to enterprise APIs with minimal changes.

As the Right Questions[1]#

Statements the API and Surounding Security Frameworks must be able to support:

  • "An application administrator can create an account for a new user."
  • "An application administrator can modify a user account."
  • "An application administrator can disable applicaiton access for user account."
  • "A end-user may require to be able to update thier email address"

Summary of the Steps:#

API modeling consists of 5 activities that help identify the requirements of your API design:
  • Identify the participants, or actors, that will interact with your API
  • Identify the activities that participants wish to achieve
  • Separate the activities into steps that the participants will perform
  • Create a list of API methods from the steps, grouped into common resource groups
  • Validate the API by using scenarios to test the completeness of the API

Step 1: Identify the Participants#

The first step in API modeling is to create a list of participants or actors that will interact with your API. This may be one or more of the following:
  • Internal developers
  • External developers
  • System administrators (i.e. your company’s administrators)
  • Account administrators (i.e. your customer’s administrators)
  • Users of the system (users, managers, moderators, etc)
  • Applications
  • Devices

Beginning with activities can lead to missed or incorrect APIs that fail to accommodate all types of participants. Listing the participants first improves the coverage of activities and helps to provide a more holistic view of how the API will be used.

For each participant, you will capture:

  • who they are
  • if they are internal or external to your company
  • a short description of who they are. For example:
System AdminInternalResponsible for managing accounts, gathering system-wide metrics
CustomerExternalA customer account
ManagerExternalA manager oversees and reports on the activity of one or more customer accounts

If you are uncertain where to start, begin with a list of specific people or roles. Then work to generalize them into a common list of partipants that best describe the types of “people that will be interacting with the API (directly or indirectly).

Also, keep in mind that internal and external systems that will integrate with your API may be considered participants as well. This is often the case with notifications and automated workflows.

With your list of participants in hand, we move to the next step: identifying the activities.

Step 2: Identify the Activities[1]#

An activity is work that produces a desired outcome and that is accomplished by one or more participants.

Activities Examples include:

  • Create User
  • Read User
  • Update User
  • Delete User
  • Resolve User login Problem

Notice that these activities likely include one or more steps required to accomplish the activity.

While we will need to go into the "how" level of granularity soon, start by looking at outcomes or goals rather the steps required to achieve the activity.

Your API may focus on only one activity; however, most APIs focus on more than one.

A single activity may require one or more participants, depending on the type of ”



APIs are becoming ubiquitous as the API Economy unfolds as their potential to transform business is becoming widely recognized. But delivering a successful API program that achieves defined business objectives requires a systematic approach to designing and managing APIs.

Great APIs are not difficult to develop if you design for your users and the business processes the API will support, if you make it easy for developers to find and consume your API, and you actively manage your API Developer Community as an extension of your business.



Scim v2 providers#


API monitoring#




API testing#

Auto-test suite


Function we need to be able to provide. create - Create a user -- All users should be created via standard SCIM calls -- Might want to ALWAYS set random password (They can always change it later)


=============================================================================== "..what's important is context control, choice and respect" =============================================================================== http://nordicapis.com/virtualization-sandboxes-playgrounds-wholesome-api/ An API is only as good as it is known. Getting an API into a developer’s hands, demonstrating the power of your solution, and providing an environment in which they can test and manipulate data in a controlled, monitored way is perhaps one of the most important unsung heroes of API publication.

More Information#

There might be more information for this subject on one of the following: