1.
The Next Step to Build Better
APIs — Consistent Data
Structure
by Andrew Turner
https://by.dialexa.com/consistent-data-structures-the-next-step-to-building-an-api

2.
Dialexa
We are on a mission to make every
company a great technology company.
We work with organizations to define and
execute digital transformation strategies to
improve business operations and customer
experiences. Our services include:
• Multi-Year Technology Roadmap
• Platform Engineering
• User Experience Design
• Custom Software Development
• Hardware Prototyping /IoT

3.
You don’t build good
APIs through coding
alone. Like any other
part of your business,
APIs are best when
they are developed as
part of a detailed,
end-to-end strategy.
Get the full write up of
this slideshare HERE

4.
However, there are multiple
parts of a comprehensive
strategy and understanding
each piece is essential to
building better APIs.
Get the full write up of
this slideshare HERE

5.
In our first post about APIs, we talked
about the need for a documentation-
first strategy and how 3 main tools can
help you build more effectively.
Get the full write up of
this slideshare HERE

6.
The next natural step in the process is to
choose an appropriate data structure formatting
convention for API endpoint responses and
ensure it is applied consistently—here’s how.
Get the full write up of
this slideshare HERE

7.
Understand Your API Use Case
Get the full write up of
this slideshare HERE

8.
We talk a lot about
“starting with the why”
for product development—
starting small discovery
projects and using design
thinking to get to the heart
of the problem your
product will solve.
Get the full write up of
this slideshare HERE

9.
Understanding the “why” is
also an important concept
when building APIs.
Get the full write up of
this slideshare HERE

10.
The key is to determine your API use
case. Is the API for a mobile app? Is it
for front end use? Will it be public for
third party developers?
Get the full write up of
this slideshare HERE

11.
The “why” of your API will help you
choose the right data structure convention
for development. However, there are many
different options to choose from.
Get the full write up of
this slideshare HERE

12.
Common API Response
Formatting Conventions
Get the full write up of
this slideshare HERE

13.
To read more you can find the full article at
https://by.dialexa.com/consistent-data-structures-the-
next-step-to-building-an-api

14.
JSON API
JSON API is a community-driven specification for building
APIs and formatting API responses.
Get the full write up of
this slideshare HERE

15.
EmberData
Ember is a framework for creating ambitious web applications.
If you're building an API for an Ember application, you may
want to consider using the EmberData convention for your API
responses.
Get the full write up of
this slideshare HERE

16.
Core API
Another community-driven convention is Core API.
Get the full write up of
this slideshare HERE

17.
Flat Response
This is a simple and straightforward way to format your data structure that
simply returns the data requested without a namespace object. Twitter and
GitHub are popular APIs that follow this data structure formatting convention.
Get the full write up of
this slideshare HERE

18.
Seeking the pros and cons of
each data structure convention
seems like a logical next step
once you’ve listed your options.
Get the full write up of
this slideshare HERE

19.
However, there is no single correct data structure
convention. You should choose a convention based
on what is pragmatic and intended for your API use case.
Get the full write up of
this slideshare HERE

20.
It’s possible that a specific data structure convention would
work best for your API's use case—for example, Vinli’s
need to return telemetry data could command a different
convention than a project management API that returns
tasks and project updates.
Get the full write up of
this slideshare HERE

21.
Generally, though,
keeping your data
structures
consistently
formatted will result
in a better API.
Get the full write up of
this slideshare HERE
Get the full write up of
this slideshare HERE

22.
When you establish
your data structure
convention from the
outset of your project,
you can better
coordinate the “why”
of your API and the
way you’re building it.
Get the full write up of
this slideshare HERE

23.
Then, you can
include the data
structure
convention in your
documentation
and use Dredd to
validate its use
throughout the
project.
Get the full write up of
this slideshare HERE

24.
After you establish a formatting
convention for your API's data
structures, you should implement
meaningful HTTP status codes
to ensure your API responses are
accurate.
Get the full write up of
this slideshare HERE

25.
Find out where great products come from!
Download or free eBook:
https://by.dialexa.com/dialexa-end-to-end-
development-guide-0

26.
Status Codes Should Accurately
Reflect Your API Response
Get the full write up of
this slideshare HERE

27.
As you use Dredd to validate your
data structure formatting, make
sure you use the appropriate
HTTP status code for each type
of response.
Get the full write up of
this slideshare HERE

28.
However, because there are
so many HTTP status codes,
it is important to pay attention
to the right ones throughout
your development process.
Get the full write up of
this slideshare HERE

29.
At a higher level, there are 4 main HTTP status code
categories:
• 200 Level: The HTTP 2xx codes convey successful responses.
• 300 Level: HTTP 3xx codes are reserved for redirects.
• 400 Level: This Block of codes conveys errors that originate on the client side.
• 500 Level: Similar to the 400 level codes, HTTP 5xx codes translate errors, but
on the server side instead.
Get the full write up of
this slideshare HERE

30.
To give you a better idea of the specific codes any engineer should
know, we’ve compiled a list of the most important ones:
Get the full write up of
this slideshare HERE

31.
By using these meaningful
status codes, you can
avoid sending 200 level
status codes when your
API is returning an error!
Get the full write up of
this slideshare HERE

32.
You want your API
to be predictable and
easy to work with—
ensuring status
codes match the true
API response is
essential to building
a better API.
Get the full write up of
this slideshare HERE

33.
There’s More to APIs and
Product Development Than
Consistent Data Structures
Get the full write up of
this slideshare HERE

34.
You won’t be able to build an effective API without
proper documentation and consistent data structures.
Get the full write up of
this slideshare HERE

35.
And you won’t be able to succeed with
digital transformation projects if you
can’t build better APIs. However, there’s
much more to digital transformation
product development than just APIs.
Get the full write up of
this slideshare HERE

36.
PROPERTY OF DIALEXA LLC ©2017 - CONFIDENTIAL & PROPRIETARY
Thank You
Doug Platts
VP of Marketing
marketing@dialexa.com
If you want to learn more about the product
development process and how your better
APIs fit into the bigger picture, download
our free ebook and discover how we
combine business and innovation consulting,
user experience design, software
engineering and hardware engineering to
create products that users love.
Get the full write up of this slideshare at https://
by.dialexa.com/consistent-data-structures-the-next-step-to-
building-an-api