PHASE 2

Design & Develop a Web API

Develop APIs That Work Properly for the Organization

Info-Tech Research Group, Inc. is a global leader in providing IT research and advice.
Info-Tech’s products and services combine actionable insight and relevant advice with
ready-to-use tools and templates that cover the full spectrum of IT concerns.
© 1997-2015 Info-Tech Research Group Inc. Info-Tech Research Group 1
Phase

1 2 3 4
PHASE
Design & Develop a Web API 2
#
Info-Tech Research Group 2
Phase 2.1: Design a web API to determine endpoints

1 2 3 4

1 Examine the Opportunities 3 Test the Web API 4 Monitor & Continuously
Web APIs Can Enable Optimize the Web API
2.1 Design a Web API

2.2 Develop a Web API

Recommended Timeline: 3 weeks

Info-Tech Insight • Web API design Deliverables from this Phase

Major created.
Milestones • Understanding of best
Reached Design
practice development
Requirements
Design your web API that promotes techniques.
speed of development and service
• Creation of business
reuse. Key Web API Design
process flow, ERD,
Activities and data flow
Completed diagrams.
• Collection of data sets
defined (as objects).
Info-Tech Research Group 3
Phase 2.1: Exercise Guide

Design your web API that promotes speed of development and service
reuse.

Design & develop a web API

2.1.1 Understand how your web API fits into your system architecture.
2.1.2 Define high-level design details.
2 2.1.3 Define your process workflows and business rules.
2.1.4 Map the relationships among data tables through ERDs.
2.1.5 Document your web API data flow diagrams.
2.1.6 Identify the integration risks, security gaps, bottlenecks, and other risks in your data
flow.
2.1.7 Define your objects by effectively referencing your data model.

3
Test the web API
3.1 Create test cases using model, synthetic, and scenario-based test design techniques.
3.2 Create a test plan for your web API.
Participants
Business Analyst(s)
Monitor and continuously optimize the web API Development Manager
4 4.1 Identify roles for your API development projects. Data Architect
4.2 Develop governance for web API development.
4.3 Measure the value of your web API project.

Info-Tech Research Group 4

 Navigate through this blueprint using the following definitions
as they relate to web API development

“The exchange of information resources facilitated by exposing your core entity’s

API Economy information resources to an ecosystem of developers through an internet-based API,
and combining other entities’ APIs to build new information resources.”
Source: Jim Plamondon. “Introducing the API Economy: A Dialogue.”

An application programming interface designed to operate over the network using

Web API web protocols.

An entity that provides/exposes the

API Provider web API. Internal/Private Web API

An off the shelf or custom application An API used to enable internal API consumers to
API Consumer that uses the web API. operate within the firewall of the organization.

A business stakeholder that uses an

End User application which internally makes use
Open/Public Web API
of the web API.
Source: Israel Gat and Giancarlo Succi.
An API exposed to API consumers outside the
firewall of the organization as well as internal API
consumers within the firewall.

Info-Tech Research Group 5

Make your web API reusable and not tied to a single business
process or application
Web API exposed to a given business
process/app.
• Design technology-agnostic APIs. This creates a shift in mindset
where web APIs move away from single point-to-point coupling (via a
Request single POST SOAP call, for example) to loosely coupled, multiple
Web API Business
Process
exposed resources for numerous applications and business
processes to take advantage of (via REST with multiple HTTP verbs
App Data
exposing resources, for example).
Response Data • Make your web API generic. There could be any number of
scenarios to access your web API. It should service more than one
process/application so that it is re-purposable and reused in various
Web API that is service oriented. ways. An example of this is the REST architectural style which
exposes a generic entity without being tightly coupled to a specific
Multiple process or application.
Request/Response
Interactions • Developing your APIs with the mindset of “code once, use many”
leads to simplified maintenance due to reusability, making it easier
for developers to understand and consume.
Multiple
Business
• Decouple formatting from data. The same URI should return data
Web API
Processes in JSON, XML, HTML, or any other format since it references the
same resource. Avoid different URIs for each format.
App Data

For more information on service orientation, refer to Info-Tech’s

research, Build an Application Integration Strategy.

Info-Tech Research Group 6

Exercise: Understand how your web API fits into your system
architecture
2.1.1 1.5 Hours

Use a consistent, standardized method to design, build, and deploy API solutions.
INPUT
• Even though organizations plan for integration initiatives in their projects, very few have
developed a holistic approach to their integration problems, resulting in each project • Existing business
deploying different tactical solutions. process documents
• Architecture provides the footings, boundaries, definitions, and dimensions of information
and application integration with your integration technologies such as ESBs and APIs.
• Without an architectural view, it is difficult to align API integration technology solutions with OUTPUT
business drivers.
• High-level system
architecture
Instructions
1. Develop a high-level system architecture in context of developing your web API with
architectural components that apply to your organization (e.g. ESB, process Materials
orchestration, web servers, partner gateway services, data, infrastructure).
• Identify specific entities pertaining to architectural components, each unique to • Whiteboard and
markers
your organization (e.g. corporate database for data architectural component).
• Web API Design
• Identify how the APIs you are developing are connected to application
Document Template
architectural components. This will drive how your API will be designed in
exercises 2.1.2 through 2.1.7. Participants
2. Document Step 1 into the Web API Design Document Template. Giving your
developers a web API design document provides them with development guidelines on • Business Analyst
interfaces and data payloads, and also gives your operations group guidance on what to • Development
expect for performance, integration, and network connectivity components. Manager

Refer to the following slide for an example of the final output of this exercise.

Info-Tech Research Group 7

 Exercise: Understand how your web API fits into your system
architecture (continued)
2.1.1 1.5 Hours

Example:
Process Orchestration BPM
Legend:
Corporate
Website HTTPS
CRM Apps Web API being
Business
Web developed
Server ERP Apps
Users

External Client ECM

Information HTTPS
Legacy Apps
Business
Partners Partner
Gateway API
s Corp. Database Private Cloud

Infrastructure

Common Infrastructure Services Process Orchestration Components

• Security Services – include security protocols and procedures for
components operating in AI environment.
• Audit Services – trace data flowing through ESB from service requestor to
provider and distribution of data.
• Monitoring and Management Services – manages system and business
processes.
• Metrics Capture Services – captures and stores operational metrics for
analysis.
• Directory and Access Services – provide directory of physical locations of
resources and end points.
• Business Processes – process rules and definitions
that are imported into the process run-time engine for
automated execution.
• Human Tasks – staff activities in a process assigned
to, and management of, the tasks.
• Business State Machines – service that maintains the
state of long running processes.
• Business Rules – rules stored in a repository and
implemented via a rules execution engine.

Info-Tech Research Group 8

Use well known web API design guidelines to prevent common
errors
A web API is exposed through HTTP as a set of generic
The Importance of API Design resources that are ultimately based on a well-defined data model.

A focus on design is a key part of ensuring user productivity Data Model Object Representation
and a good ROI for the solution. A poor design will frustrate
developers and lead to longer development cycles or complete App Interface HTTP
abandonment of the solution. A well-designed web API will be from_resource()

simple to understand, consistent in its usage, and stable. application/x-resource

to_resource()
Well-designed web APIs tend to get reused – this leads to a App Web API API
higher return on the investment, improved code quality through Consumer
reuse, and design simplification. Source: Jansen, Geert. “The Job of the API Designer.”

• In the design stage, expect to go through several iterations before settling on a stable It is worthwhile saying that you
web API. It is more cost effective to design a web API with initial expected should develop an API with the end
functionality and include additional features once more use cases come to light. user in mind, and it’s something that
◦ Determine and document what your web API is trying to accomplish for your needs to be reinforced continually.
web API consumers. The people providing the API as a
◦ Determine what the use cases of your web API will be. Brainstorm and interview service have a certain perspective on
as many potential web API consumers as possible to determine these use cases. the technology they’re building. It’s
◦ Determine how these use cases would translate into specifications for your web necessary to be able to step out of that
API. Keep these specifications short as they will be easier to modify. Determine perspective and consider the
each specification’s appropriateness to the web API. For API specifications, technology being used to implement
categorize each specification into: (1) routines, (2) data structure, (3) object class, the clients to the API and what those
(4) methods, (5) parameters, and (6) variables. client developers are trying to
- When in doubt, leave it out. It’s better to leave out specifications that you achieve.”
are unsure of. – Ken Toole, Senior Director of
Engineering at Adobe Systems
Info-Tech Research Group 9
Run your design sessions as a product development effort
aimed at the consumer of your web API
Establish the key objectives for your web API in order to obtain the right
resourcing to deliver a suitable product.
Involve Key Stakeholders Info-Tech Insight

• A team of development and data experts need to be intimately involved at • API development is driven from the
this stage as there are many possible implementations for a given set of outside in with clear intent. What you
business requirements.
• Also, consider including the following roles:
are trying to achieve will drive many of
o Business Process Owner the design decisions and make it
o Test Lead easier for web API consumers to
understand. It is aimed at improving
the productivity of those who will
Follow Best Practices consume your API.
• Use a multi-pass design approach, where optimization is progressive.
• Conduct an ongoing cost/benefit analysis looking at the trade-offs • Don’t count on your initial API
between short- and long-term objectives. design reaching stability right away.
• Sometimes a less than optimal solution is necessary so that the overall Design efforts can continue for a long
organization benefits through standardization. time since it is an iterative process. Aim
for a minimum viable product at each
We try to provide APIs that are clear in their intent and usage so that iteration rather than trying to over-
you can avoid having clients make assumptions that are invalid. As a engineer a web API.
service provider, you have to take a bit of ownership over, “Did you
provide an API that allowed clients to do things that become • Document your changes as part of
problematic in the future, or were you very clear and explicit about an overall enterprise architecture.
how your API should be used in the design of the API itself?” This will enable discussions related to
– Ken Toole, Senior Director of Engineering at Adobe Systems impact analysis for process or system
changes to be simplified.
Use these best practices to define API requirements, use cases, and
design entities in the next exercise.

Info-Tech Research Group 10

Exercise: Define high-level design details based on web API
requirements
2.1.2 1.5 Hours

Instructions INPUT
1. As a team, define your web API requirements (business, functional, non-functional). • Web API use cases
Brainstorm the use cases of how your web API will be used by API consumers. For more from the business
information on defining requirements and use cases, and design techniques, please refer to
Info-Tech’s blueprint on Application Development.
2. Using the sticky notes and the whiteboard, define design entities for your web API based on OUTPUT
requirements. Map design entities to the requirements and use cases of your web API.
• Web API use cases
3. Document steps 1 and 2 in the Design Requirements Template.
• Design entities for
web API
RQMT RQMT RQMT
1 2 3 Materials
• Whiteboard and
markers
USE • Sticky notes
CASE • Design Requirements
USE USE Template
USE
CASE CASE
CASE
Participants
• Business Analyst
• Development
DESIGN DESIGN Manager
DESIGN ENTITY ENTITY
ENTITY DESIGN
ENTITY

Info-Tech Research Group 11

Design and document detailed web API functionality around
the consumer of your web API
Define the dialogue between the web API and its consumer that satisfies the
requirements and processes set by the business.
• Business process owners can collaborate on improving existing processes based on the design entities
and requirements set out in Exercise 3.1.

• In some cases, multiple processes can benefit from a single web API.
• Use the detailed design to provide context for business use cases which, in turn, can be used to create
functional test cases for applications that make use of each web API.

Make It Happen:
• List all the business rules in a given process. This can be done by initially looking at decision points
within each process flow. You can create test cases to ensure your web API works under those
conditions.

• Determine the URI filters based on how your web API will be consumed. If, for example, most
cases only require a subset of the entire data available, don’t send all the data unless a particular flag
has been set in the URI.

• Design your web API to be consumed easily. If the API consumer is expecting JSON data, for
example, but your web API only offers XML, that will require additional development effort which could
make your web API less attractive.

Info-Tech Research Group 12

Exercise: Define your process workflows and business rules
2.1.3 2 Hours

Instructions INPUT
1. Map the high-level step-by-step process of the use case to show your best estimate at the
• Existing business
intent of how the web API will be used.
process documents
2. Identify where business rules exist in the process workflow.
3. Identify which business processes belong to a specific application/system. Then, identify
where web API integration is required. OUTPUT
4. Document steps 1 through 3 in the Web API Design Document Template.
• Business process
Example:
workflow

Above/Below $5,000
Budget?
Materials
Create a Get Finance Generate Email
• Whiteboard and
Campaign Approval Below Budget List
markers
• Web API Design
Above Budget Document Template
JSON
Get Additional data Participants
exchange
Funds • Business Analyst
• Development
Manager
Push Emails
Launch
Into Email
Campaign
server
Info-Tech Research Group 13
Map the relationships among data tables through Entity
Relationship Diagrams (ERD)
Use ERDs to document the relationships and understand the construction of
objects exposed by your web API.
Why is it important?
• You need to understand how internal objects are connected for maintenance purposes. Entity
relationship diagrams describe how one data set (entity) uses or points to another entity. Actions indicate
the purpose or logic behind the use of each entity.
• Your data may be coming from different systems that require customization to support your web
API. The ERD could be an abstracted view of a database and the relationships among multiple
databases which all need to be based on the same semantic understanding.
• To serve as a framework for developing wireframes and storyboards. Each entity can be an
interface with each data type as an interaction object and in which the action defines the interactions
between the wireframes of a storyboard.
How should ERDs be created and documented?
• Elicit process descriptions and make all nouns into entities, noting any hierarchical dependencies
between them.
• Begin with an end user or requirement and flush out the types of data required to support each use
case.

Info-Tech Research Group 14

Exercise: Map the relationships among data tables through
ERDs
2.1.4 1.5 Hours

Instructions INPUT
1. Determine hierarchical model will be used to create your entity-relationship diagram (Class
• Documentation on
Type, Ownership, or Association).
data sets
2. Denote all data sets into data tables. Map data tables that will be specifically exposed by
the web API being developed. If you are not certain which ones will be exposed, include all
data tables that you would think would be valuable to the API consumer.
OUTPUT
3. Map relationships among data tables. This will depend on the hierarchical model used.
Make sure to define the actions between entities which will map the interaction workflow • Entity relationship
from one data set to another. diagram
4. Document steps 1 through 3 in the Web API Design Document Template.
Example:
Materials
Campaign Customer Organization
• Whiteboard and
Name FirstName OrgName markers
• Web API Design
Description LastName Address
Document Template
StartDate Role Phone
Participants
EndDate Organization City

Type Revenue • Data Architect

Invoice
• Development
Channels InvoiceNumber Manager

Description Items

Availability Date

Info-Tech Research Group 15

Document your web API inputs and outputs through data flow
diagrams

Why is this important?

• Exposing the appropriate information and data is critical for your web API to be successful. Without the
right data, there is risk of disruption to the business.

• Identifying data inputs and outputs can lead to discussions around establishing the true source of data
within the enterprise.

• It can help assess the payload necessary and provide insight into network traffic and possibly
performance issues.

How is it typically done?

• Standard practice is to use a data flow diagram. The diagram traces all data from creation inside the
web API to final consumption and storage.

• In some cases data may not be immediately available due to dependencies from other systems, which
leads to discussions around workarounds. Temporal aspects of data are documented in the data flow
diagram.

• Security restrictions should be documented in the data flow diagram including firewall port requirements
and payload limitations.

Info-Tech Research Group 16

Exercise: Document your web API data flow diagrams
2.1.5 2 Hours

Instructions INPUT
1. In process flow-like diagram, determine how each data set relates to another using verbs • Documentation on
that are based on HTTP methods. data sets
2. For each data set, determine all associated attribute variables and function methods.
3. Identify in your data flow diagram where data integration is required. This will be where your
web API be located. OUTPUT
4. Consider the following when conducting this activity:
• Is the data read-only or can the application and users edit and modify it? • Data flow diagrams
• Which components are managed and operated by third-party providers? What is
your level of control?
• What is the taxonomy of data in your system? Is it standardized and is the data
encrypted? Materials
• How often are your databases updated? Is it real-time or periodic extract, transfer,
• Whiteboard and
and load (ETL)? markers
Example: • Web API Design
Customer Account Manager Document Template
GET Account Manager
FirstName Name Participants
POST Customer
LastName Customer • Data Architect
• Development
Role Level CRM ERP
Manager
Organization
API
Type Private Cloud

Info-Tech Research Group 17

Exercise: Identify the integration risks, security gaps,
bottlenecks, and other risks in your data flow
2.1.6 1.5 Hours

• APIs are critical components of your system architecture which provide access to native INPUT
hardware features and facilitate communication with enterprise systems, third-party
services, and other devices. • Documentation on
• By not paying attention to your API development, you risk: data sets
o Heavy-weight communication over slow mobile networks which will drive down
performance.
o App misuse due to exposed and unsecured APIs. OUTPUT
o Unavailable services because APIs do not accommodate changing end points
and fragmented data schemas. • Data flow diagrams
• Identifying potential risks associated with data exposed by your web are important when
determining the development practices that need to be used to mitigate those risks.

Instructions Materials
1. Using your data flow diagram as a reference, identify existing and potential • Whiteboard and
markers
performance bottlenecks, security gaps, integration issues, and other • Web API Design
technical issues. Document Template
2. Write your gaps on sticky notes and place them on top of your diagram.
3. Determine development-related practices that mitigate the identified risks for Participants
successful API development. Write these practices on sticky notes and place • Data Architect
them on top of the gaps on your data flow diagram. • Development
Manager
Refer to the following slides for leading questions to reveal current or potential security,
performance, and integration risks in your data flow and for an example of the final output of this
exercise.

Info-Tech Research Group 18

Exercise: Identify the integration risks, security gaps,
bottlenecks, and other risks in your data flow (continued)
2.1.6 1.5 Hours

Leading questions to ask when assessing your API data flow:

Security
• What data needs to be secured
during transit?
• What might cause data to be
tampered with?
• What data is trusted vs. untrusted?
• Do work products from partners,
collaborators, subcontractors, or
suppliers meet your security
requirements?
• Is the application able to adapt to
changing circumstances that affect
its ability to meet its security
objectives?
• Do the architecture and design
sufficiently address security?
• Are end users and administrators
verified upon application spin up
and spin down?
• Does the system comply with
applicable security policies, laws,
and regulations?
Performance
• What may cause performance
bottlenecks with in-house servers
(e.g. server load balancing issues,
internet connection)?
• Is the load properly distributed
across various device hardware and
system components?
• How many tasks are suspended and
delayed due to slow executions of
other tasks?
• What level of control do you have
over backend infrastructure and the
code of your applications?
• Does the frequency of data
refreshes consume significant
battery and processing power?
• Does information flow through a
single module, an API, or hardware?
• Do your applications heavily rely on
the web for operations?
Integration
• What information and data are
exchanged within your flow? Does it
need to be secured?
• What integration approaches in your
stack are not scalable to increased
loads (e.g. point-to-point, adapter,
ESB, middleware, API gateway)?
• Is your API dependent on other
applications, hardware, or systems?
• What web communication protocols
and standards are used by existing
applications, data, APIs, and
infrastructure? Are they scalable?
• What is the format of the payload
transported over your APIs (e.g.
XML, JSON)?
• What level of customization do you
have over your third-party APIs?
• Are your APIs standardized and
documented?

Info-Tech Research Group 19

 Exercise: Identify the integration risks, security gaps,
bottlenecks, and other risks in your data flow (continued)
2.1.6 1.5 Hours

Example:
High Payload, Data
Encryption
Legend:
Slow
Application CRM
Execution
ERP
API Risk of Data Performance
Consistent
Leak Issue
Object
Notation
Data Customers Account Manager Security Gap

Managed by Integration
Infrastructure Corp. Database Private Cloud
Third Party Risk

Solution
Customer Account Manager
GET Account Manager
FirstName Name
POST Customer
LastName Customer

Role Level CRM ERP

Organization
API
Type Private Cloud

Info-Tech Research Group 20

Define your objects by effectively referencing your data model

Info-Tech recommends using a REST architecture style for API development.

Define the objects that your web API will expose (endpoints).
• Focus on how your objects are defined and less on data representation. Within the data that you exposing, it is important to
determine how a collection of data sets will be represented for API exposure. Define objects that are intuitive for your API
consumer to request for. Representation formats for data (e.g. XML, JSON) are always changing – ensure that you are able
accommodate for these appropriately (demonstrated in the content-type of a request).
• Define objects as nouns and plural-based. A collection of data sets indicates that there is multiple entities associated with a
object – make your objects intuitive for the API consumer. Objects should also be noun form (e.g. /customers, NOT
/getcustomers) for scalability at the API layer.
/customers Web Server
API
GET /customers
Consumer calls
Content-Type: application/json
Request Customer Location
Data Set
Data Modeling Account
(Collection)

Class Design Considerations

• Minimize the amount of change that occurs by defining classes/data sets as immutable. If you do design your web API to
have mutable classes, keep them well-defined and be clear when it is legal to call specific methods. Having immutable classes
and thereby objects will make your code thread-safe and reusable in the long term.
Method Design Considerations
• Adhere to consistent semantics throughout the API, other APIs, and connecting platforms. Keeping naming conventions of
requests consistent with other software components will create less hardship for maintenance in the long term. An approach is to
keep your actions separate from your objects for your methods (e.g. HTTP methods GET, POST, PUT, DELETE).
• Avoid long parameter lists to avoid payload issues for responses. This can be done by either using the break up method or
creating a helper class to house parameters.
• Use consistent parameter orderings across methods. Regardless of the parameter’s semantical significance or the
importance to a particular method, it is more important to have parameter orderings consistent where possible for greater API
performance.
Source: Bloch, Joshua. “How to Design a Good API and Why It Matters”.

Info-Tech Research Group 21

Exercise: Define your objects by effectively referencing your
data model
2.1.7 1.5 Hours

Instructions INPUT
1. Based on the data flow diagram created in 2.1.3, group data sets into objects. Name the
objects in plural and as nouns. • Documentation on
data sets
2. Document step 1 in the Web API Design Document Template.

OUTPUT
Example:
• Data flow diagrams
/customers with web service
objects defined

Customer Account Manager

Materials
FirstName Name
GET customers
• Whiteboard and
LastName Customer markers
CRM ERP • Web API Design
Role Level
Document Template
Organization
API Participants
Revenue
Private Cloud • Data Architect
• Development
Manager

Info-Tech Research Group 22

Phase 2.2: Develop a web API with considerations made for
how it will be consumed

1 2 3 4

1 Examine the Opportunities 3 Test the Web API 4 Monitor & Continuously
Web APIs Can Enable Optimize the Web API
2.1 Design a Web API

2.2 Develop a Web API

Recommended Timeline: Two Months

Info-Tech Insight • Understanding of best- Deliverables from this Phase

Major practice development
Milestones techniques.
Reached No deliverables created for this
Be consistent end-to-end when phase.
developing your web API. Target
developers will find your API easy to
• No activities for this
adopt if your API base format is Key section.
similar to their application. Activities
Completed

Info-Tech Research Group 23

Develop your web API with HTTP override to allow
consumption through firewall restrictions
When It Should Be Used
HTTP Override Example:
• If the client side won’t support a particular
HTTP verb that you have built into your
design. This allows web API clients to use POST /customers/cust1
your services in accordance with their
Host: myuri:8080
firewall restrictions.
Content-Type: application/json
X-HTTP-Method-Override: PUT
How HTTP Override Works Cache-Control: no-cache

• The client side injects a X-HTTP-Method- Example Description:

Override header in the request.
• The client side submits a POST request which needs to
• Your API accepts the request, looks for the be redirected in your web API as a PUT request.
X-HTTP-Method-Override header, and
redirects the request using the appropriate HTTP/1.1 200 OK
POST /customers/cust1
verb. ...
…
X-HTTP-Method-Override: PUT
• The client side receives the appropriate
information.

Considerations
Web API API
Consumer
• Be prepared for extra development and
testing required to support the override.

Info-Tech Research Group 24

Include content negotiation to prolong the stability of your
web API
When It Should Be Used
• When you want a single resource-based
URI endpoint to output data in multiple
formats. This type of design promotes long-
term reuse and separates format from the
resource.
How Content Negotiation Works
• The resource URI is called by the client side
along with an Accept request header for all
content that is acceptable along with a
relative quality factor (between 0 and 1).
• Your web API can send the same data in
various formats best suited to the API client
environment.
Considerations
• Be prepared for designing your web API so
that each format can be supported. Non-
alphanumeric characters can sometimes
throw off the formatting.
Content Negotiation Example:
GET /customers/cust1
Accept: application/json
application/xml; q=0.8
application/rss+xml; q=0.5
Example Description:
• In this example, the client side submits a GET request for
a customer resource which your web API will try and send
in JSON format, followed by XML and RSS.
GET /customers/cust1
HTTP/1.1 200 OK Accept: application/json
… application/xml; q=0.8
application/rss+xml; q=0.5
API
Web API
Consumer
Info-Tech Research Group 25
Return status codes for all requests in a way that is consistent
with the web
When It Should Be Used
Status Code Returns Example:
• Each time a call is made to your web API, a
status should be returned so the caller HTTP/1.1 400 Bad Request
knows whether the result was successful or Content-Type: application/json
not. {
“errorcode”:”1234”,
“message”:”Incorrect request”,
How Status Code Return Works “docurl”:”http://mysite.com/errors/1234”
}

Example Description:
• There are well known HTTP response
• In this example, the client side submits a bad request
codes that should be passed after a
which your web API will capture and send an error status
response has been processed.
with additional details in JSON format.
• Provide an additional payload information to
assist developers who use your web API HTTP/1.1 400 Bad Request GET /customers/cust10
during development and troubleshooting. ... ...

Considerations
• Lack of industry consistency. Facebook, for API
Web API
example, returns only status code 200 with Consumer
error messages in the payload. Twilio provides
hyperlinks in their payload to aid in
troubleshooting.

Info-Tech Research Group 26

Use generators and reuse existing web APIs if they already
exist
Use existing resources in the industry to accelerate development. Don’t waste time
developing commoditized components and libraries – focus your efforts on where you
can add business value.

Pre-Existing Web APIs

• Explore the web for existing web APIs in the industry that already provide the functionality you intend to offer.
Search through well known portals such as:
o APIs.io (search engine for APIs)
o ProgrammableWeb (community portal that includes a search engine for APIs and news)
o Google APIs Explorer (list of APIs for working inside Google’s ecosystem)

SDK & Pattern Generators

• These types of tools are use for wrapping your API into reusable components. Examples include:
o Swagger (includes client SDK generation, discoverability, and interactive documentation)
o RAML (a YAML-based modeling language for your web API)

Schema Generation Tools

• These types of tools enable sharing for portable JSON schemas with partners or an internal standard. Examples
include:
o JSON-Schema (a list of validators, generators, and parsers for various platforms and languages)

Generate documentation for your web APIs Train your team on proper design of APIs
• API Academy
• APIBlueprint
• Pluralsight

Info-Tech Research Group 27

Phase 2 outline
Call 1-888-670-8889 or email GuidedImplementations@InfoTech.com for more information.

Complete these steps on your own, or call us to complete a guided implementation. A guided implementation is a series of 2-
3 advisory calls that help you execute each phase of a project. They are included in most advisory memberships.

Guided Implementation 2: Design and Develop a Web API

Proposed Time to Completion: 8 weeks

Phase 2: Design and Develop a Web API

Start with an analyst kick off call:
• Identify the design and development gaps that need to be addressed.
• Review design and development practices outlined by Info-Tech.

Then complete these activities…

2.1.1 Understand how your web API fits into your system architecture.
2.1.2 Define high-level design details based on web API requirements.
2.1.3 Define your process workflows and business rules.
2.1.4 Map the relationships among data tables through ERDs.
2.1.5 Document your web API data flow diagrams.
2.1.6 Identify the integration risks, security gaps, bottlenecks, and other risks in your data flow.
2.1.7 Define your objects by effectively referencing your data model.
With these tools & templates:
Design Requirements Template
Web API Design Document Template

Phase 2 Results:
• Understanding of best practices for design and development for web APIs.
• Web API design created.

Info-Tech Research Group 28

If you want additional support, have our analysts guide
you through this phase as part of an Info-Tech workshop
Book a workshop with an Info-Tech Analyst

Understand how your web API fits into your system architecture
2.1.1
The facilitator will walk you through the exercise of developing a high-level system
architecture to determine how your web API development project fits into your
business processes.

Define high-level design details based on web API requirements

2.1.2 Info-Tech will facilitate discussion around how the web API should be designed
based on requirements and use cases.

Define your process workflows and business rules

2.1.3 Info-Tech will facilitate discussion on the current state of your business process and
walk you through an exercise on mapping your business processes using process
workflow diagrams.

Info-Tech Research Group 29

If you want additional support, have our analysts guide
you through this phase as part of an Info-Tech workshop
Book a workshop with an Info-Tech Analyst

Map the relationships among data tables through ERDs

2.1.4 Info-Tech will facilitate discussion on the current state of your data and walk you
through an exercise on mapping your relationships between data sets using entity
relationship diagrams.

Document your web API data flow diagrams

2.1.5
Info-Tech will facilitate discussion around the current state of your data and walk
through an exercise on mapping your data model using data flow diagrams.

Identify the integration risks, security gaps, bottlenecks, and other

risks in your data flow
2.1.6 Info-Tech will facilitate discussion on drawing out risks associated with your data flow
for your API. The facilitator will also help you determine development practices to
minimize these risks.

Info-Tech Research Group 30

If you want additional support, have our analysts guide
you through this phase as part of an Info-Tech workshop
Book a workshop with an Info-Tech Analyst

Define your objects by effectively referencing your data model

2.1.7 The facilitator will walk through an exercise on how to create data collections
(objects) for web service exposure.

Info-Tech Research Group 31