DRAFT
The Business of Creating Well Defined APIs
As the application economy advances, so too does the need for backend
systems to support rapid, lightweight integrations. Applications which “do not
play well with others” due to clunky or non-existent integration capabilities
risk losing market share to their more flexible and attractive competitors.
Today’s software needs to be ready to work with tomorrow’s applications and
to do this sustainably, interoperability must be built into the product design
from the start—not added as an afterthought.
Why do integrations fail?
Traditionally, software applications were designed in silos to accomplish specific functions and often
worked within a custom architecture that bore little resemblance to the other application architectures
with which it would be deployed. Bridging the gap between two application silos often required deep
product knowledge, strong scripting skills and even a healthy dose of luck.
The modern approach to integration leverages application programming Interfaces (APIs) to provide
gateways that can be used to tap into specific product functionality.
Every day billions of APIs are executed to run our businesses—and those numbers are continually increasing.
Transactions per
day processed
through APIs
“
1T
5B
13B
.com
generates more than
half of its $2.3 billion
in revenue through its APIs,
not its user interfaces.”
source: Forbes.com, Welcome to the API Economy, 2012, Eric Savitz.
But not all APIs are created equal—and simply publishing APIs is not enough. APIs should be well defined,
with clear guidelines for use, to minimize end user frustration and maximize potential for (re)use. To
accomplish this, consistent API standards need to be part of the design process. Although this requires more
up front work, it can make the development process smoother and position the application for future growth.
2 | THE BUSINESS OF CREATING WELL DEFINED APIS
ca.com
What is a well-defined API?
Much has been written about the tools, technologies, protocols and standards for designing, developing,
testing, deploying and managing APIs, but what is often neglected in these discussions are the best
practices for creating well-formed, well-structured web services/APIs. To achieve the business needs and
purposes for which they are designed, APIs expose information and resources in the form of entity types
and their relationships.
Entity types are named structures with keys and consist of properties. Entity properties are unique
elements/fields within an entity type and have parameters associated with them, including name,
description, data type, default value(s) and acceptable values.
Entity relationships describe how entities interact and relate to each other and, possibly, themselves.
Types of entity relationships include one-to-one, one-to-many and many-to-many.
When these entity types and their relationships are clearly defined, the APIs that employ them are easier
to understand, maintain and use.
As a concrete example, consider service management. After reviewing business scenarios for typical
service management implementations, we identified the following service management related entity
types. By using these entity types and their relationships, it is easy to implement various Service
Management capabilities, including:
• Incident Management
• User Management
• Request Management
• Alert Management
• Change Management
Entity Type
Entity
Category
Description
Alert
Primary
This is a notification that a significant event has occurred, a threshold has
been reached, something has changed, or a failure has occurred. An alert
is generated when some type of intervention is required.
Asset
Foundational
This is a resource, a capability or anything that can contribute to the
delivery of service
Attachment
Secondary
This is a document, of some sort, that provides information or clarification
to a primary entity.
Change Order
Primary
This is a formal proposal for a change to be made. It includes details
of the proposed change.
CI Relationship
Secondary
This is a relationship between different configuration items.
Comment
Secondary
This is an annotation or update to a primary entity.
Company
Foundational
This is information pertaining to a company
Configuration Item (CI)
Foundational
This is any component or service asset that needs to be managed in order
to deliver an IT service.
Incident
Primary
This is an unplanned disruption or degradation of service.
3 | THE BUSINESS OF CREATING WELL DEFINED APIS
ca.com
Knowledge
Primary
Knowledge management (KM) is the process of capturing, developing,
sharing and effectively using organisational knowledge.
Location
Foundational
This is information pertaining to a physical location.
Organization
Foundational
This is information pertaining to a logical grouping of people.
• This can be the occurrence of same incident many times.
• This can an incident that impacts many users.
Problem
Primary
Request
Primary
This is a request is from a User for information or advice or for a standard
change or for access to an IT service.
Task
Secondary
This is a piece of work associated with a primary entity.
Tenant
Foundational
This is a logical grouping of people allowed to use a service provided
by a service provider.
User
Foundational
This is a person who accesses and uses the service.
UserGroup
Foundational
This is a logical grouping of users.
• This can be the result of network diagnostics revealing systems
not operating in the expected way.
To better understand the relationships and navigation between these entity types, we grouped the entities
into three categories:
• Foundational: these entities provide the “foundation” which the primary entities leverage. They tend to
be application agnostic.
• Primary: these entities are transactional in nature. Usually, the application is designed to manage
primary entities.
• Secondary: these entities supplement primary entities. For example, comments and attachments add
information to incidents and alerts.
Using these above entities we will discuss how to describe the entities, their associations and naming conventions.
API Entities
Entity definitions should identify all optional and required properties associated with an instance of an
entity. Each entity must also include a key (for example, OData does not allow an entity without a defined
key). Other information, such as data types, default values, accepted and navigation properties (references
to other properties), will also need to be defined for each entity property.
When defining entities you should first focus what we class as “foundation entities.” These are entities
that are required by other entities and, therefore, should be defined first. Examples of a foundation
entities would be: Tenant, User, Usergroup, Company, Location organization, etc.
Here you can see an example of the relationships between the different foundation entities from the User
entity viewpoint. It has various entity relationships with the following entities: Tenant, Location, User,
UserGroup, Company and Organization.
4 | THE BUSINESS OF CREATING WELL DEFINED APIS
ca.com
User
Legend
Can have one
Tenant
Can have multiple
tenants
Many to Many
Entity Name
Entity Properties
Navigation Properties
Location
locations
creationUserID
deletionUserID
updatedByUserID
managerUserID
description
id
tenantID
isActive
updatedActivity
name
originationURI
originatingID
employeeID
userName
customProperties
password
businessEmail
alternateEmail
comboName
locationID
title
firstName
middleNames
familyName
jobTitle
companyID
businessPhone
mobilePhone
alternatePhone
timeZone
startDate
orginationID
creationTimeStamp
deletionTimeStamp
updatedTimeStamp
User
creationUserIDUsers
deletionUserIDUsers
updatedByUserIDUsers
managerUserIDUsers
UserGroup
userGroups
Company
companies
Organization
organizations
The CI relationship entity, shown below, is an example that shows how to create a relationship between
two instances of the same entity. In this case, a provider CI and dependent CI. The relationshipType
defines the semantics (is hosted by, connected to, supports, etc.) of the relationship between the CI
instances. The CI relationship entity can then be used to determine things like: what CIs are included in a
business service, what CIs are impacted by an outage, etc., by following the provider or dependent CI
links recursively.
5 | THE BUSINESS OF CREATING WELL DEFINED APIS
ca.com
Legend
Can have one
Tenant
Can have multiple
tenants
Many to Many
CI
Entity Name
Entity Properties
Navigation Properties
providerCIIDCIs
dependentCIIDCIs
collectionCIIDIs
CI Relationship
User
creationUserID
deletionUserID
updatedByUserID
description
id
tenantID
isActive
updatedActivity
name
originationURI
originatingID
customProperties
relationshipType
relationshipSource
providerCIID
dependentCIID
collectionCIID
significance
creationTimeStamp
updatedTimeStamp
deletionTimeStamp
creationUserIDUsers
deletionUserIDUsers
updatedByUserIDUsers
Naming Conventions
Following a consistent naming convention for entities and their properties helps avoid duplication and
confusion. For names incorporating more than one word use of camelCase is recommended for ease of
reading. For example, “user group” would be expressed as “userGroup”.
We utilized the following naming conventions:
• Entity Names: Describes what the entity is. Expressed as one word where all letters are in lowercase
except for the first letter of logical words.
Examples: User, UserGroup, Problem, Change, Company, etc.
• Entity Sets Names: Refers to the entity collection, so name should be the plural of the associated entity.
Examples: Users, UserGroups, Problems, Changes, Companies, etc.
• Property Names: Describes what the property is. If possible, reuse the USM name where it makes sense.
Examples: userID, firstName, zipCode, company, etc.
• Navigation Property Names: Refers to a collection of the entity therefore use the associated entity set
name as the navigation property name except when there are multiple navigation properties within an
entity that are associated to the same entity. In this case, the navigation property name should be the
property name appended with the entity set name.
Examples: creationUserIDUsers, ownerUserIDUsers, assets, incidents, alerts, etc.
• Method Identifiers: The first word describes the action being performed and the next words list the
entity or entities that are involved. The entity will be singular if an ID is required or plural if multiple
instances of an entity can be acted upon. If linking two entities then both entities will be in the method
identifier name with the word “to” if linking the entities or “from” if un-linking the entities or “For” if
getting the links.
Examples: Using the Incident Entity:
6 | THE BUSINESS OF CREATING WELL DEFINED APIS
ca.com
Method Identifier
Operation
Resource
Comments
getIncidents
GET
{base URL}/Incidents
get all incidents
getIncidents
GET
{base URL}/Incidents(‘{id}’)
get incident by id
createIncident
POST
{base URL}/Incidents
create incident
updateIncident
PATCH
{base URL}/Incidents(‘{id}’)
update incident, just specific properties
deleteIncident
DELETE
{base URL}/Incidents(‘{id}’)
delete incident
deleteIncident
GET
{base URL}/Incidents/$count
get count incidents
Versioning Support and Backwards Compatibility
New API versions should be easy to implement and identify. The key principles of API versioning are:
• Ensure backward compatibility to not break existing clients.
• Simplify the upgrade process—should be easy to upgrade.
• Minimize the time required to upgrade.
Common methods for implementing API versioning include:
• URI versioning
• Content type versioning
• Schema versioning
• Application routing
• Making all or as many as possible entity attributes optional
Each method has different advantages and trade-offs.
URI Versioning
Including the version number in the name is a common approach. For example:
http://mysystem/api/v1/Users
Where “v1” indicates that this is version 1.
There are some challenges to this method. The version URIs are embedded in several different applications/
clients. Every time you make a change, you will need to create another environment to support existing
clients and maintain multiple systems and ensure that the other systems are upgraded as well.
7 | THE BUSINESS OF CREATING WELL DEFINED APIS
ca.com
To make this versioning work, consider categorizing the changes as “representation format changes” and
“resource changes.” Representation format changes are normally changes to the API response, such as
adding a new entity property, whereas, resource changes are things like adding new methods, such get
user by id. Resource changes will have no impact to the existing client while new clients can take the
advantage of the changes using the new resource name. Representation format changes will need to be
reviewed to determine the correct option. The possible options are:
• Create a new version.
• Add a new method identifier.
• Add change to the existing method without version change.
The version number should be classed as a major version only when there are significant changes. The
best practice is to use the same version number for all the method identifiers in the entity since having a
different version number at the method identifier level can be confusing and difficult to maintain.
Content Type Versioning
Context type versioning follows “hypertext as the engine of application state” (HATEOS) where everything
is defined. The version detail links are added as part of the Accept headers in the format of the response
you require, such as XML, JSON, etc. For example:
Accept: application/vnd.example.link_templates+v2+json
The downside to this approach is that the client needs to maintain the Accept headers which can
introduce errors.
Schema Versioning
Schema versioning is based on schema rather than the API and is passed during initialization. This
requires a high competency level to implement and should be considered only if the right skillset is
available.
Application Routing
This approach includes both full application routing and controller routing which can be handled in the
HTTP controller code. This method is commonly used in a SaaS type environment, as the application
container is light and has data segregation. Another instance is created and intelligent routing is carried
out based on client requirements. Products such as CA API Portal (Layer 7) allows you to do this at a
granular level.
8 | THE BUSINESS OF CREATING WELL DEFINED APIS
ca.com
Summary
Based on our work defining the service management related entity types, we concluded that well-formed,
well-structured APIs adhered to the following best practices:
• Clear definitions and guidelines for entity properties, including naming conventions, primitive types,
default and acceptable values
• Consistent rules for entity navigation, including one-to-many, many-to-many relationships
• Well established entity hierarchy, including foundational entities, primary entities, supporting entities
and parent/child entity hierarchy
• Auto-generation and population of entity properties
• Audit controls
• Use of versioning for both the entity properties and the APIs
• Support for extensibility, including forward and backward compatibility
• Ability to leverage virtualization
For further reading, a good reference is: Amundsen, Mike, et al. RESTful Web APIs. Sebastopol: O’Reilly
Media, 2015. Print.
Connect with CA Technologies at ca.com
CA Technologies (NASDAQ: CA) creates software that fuels transformation for companies and enables
them to seize the opportunities of the application economy. Software is at the heart of every business, in
every industry. From planning to development to management and security, CA is working with companies
worldwide to change the way we live, transact and communicate – across mobile, private and public
cloud, distributed and mainframe environments. Learn more at ca.com.
Copyright © 2015 CA. All rights reserved. All trademarks, trade names, service marks and logos referenced herein belong to their respective companies.
CS200_156820_1015