Why your APIs should fly first class

1. Why Your APIs
Should Fly First
Class
DeveloperWeek 2021
1

2. 1
$ whoami
2
Agenda
2
What is an API
first mentality?
3
How we build
APIs first
4
“Build for two”
5
Tools and tricks
6
Finish!

3. $ whoami
My name is Robert Ross, I’m the co-founder and CEO of
FireHydrant, an incident management tool.
3
bobbytables bobbytables

4. Terms
So we’re all on the same page
● An API is a REST API accessed via
HTTP
● An Actor is a person, integration,
or 3rd party performing actions
● A Frontend is a javascript
application that talks to your API
4

5. The Frontend
Matters
More than ever
5

6. Dynamic frontend experiences are valuable
This expectation likely comes from their experience with Facebook, Netflix, and
other large tech firms with the resources to invest in complex frontend
architectures.
6

7. Dynamic frontend experiences are valuable
A dynamic frontend experience
gives the same sense of quality that
a good thud of a car door gives.
7

8. Dynamic frontend experiences are valuable
It’s a sad reality, but if your
website just doesn’t have a
particular type of fancy sizzle to
it, customers may think it’s
“cheap.”
8

9. A dynamic frontend experience is a risk
9

10. Do you move that chess piece early?
Hint: Yes
10

11. The Bet We Made
● We made a bet in the first days of FireHydrant to
build an API for everything.
● We’ve amassed over 130 public API endpoints in just
over 2 years.
● We built React+Redux frontends from day 1.
● Every feature that FireHydrant exposes in the UI has
an underlying API that our customers can integrate
against.
11

12. An early goal for
FireHydrant
Be an integration platform
12

13. Be an integratable platform
● This means everything our platform could do, our customers can also
programmatically integrate with us
● It also meant that we had to consider our API design earlier than most
startups do
13

14. Be an integratable platform
● An API first mentality also changed our database design to accompany
different actors
● We built a frontend accessing an API from the start, creating the need for
well defined engineering roles early on.
14

15. Why don’t most
companies do this?
15

16. “It’s expensive”
● Building an API first and then building a
frontend is more expensive… initially.
● Eventually the benefit of having that API early
will exceed that initial cost by orders of
magnitude.
○ Want to release a mobile app in 2 years? Guess
what, you have an API already.
○ Customers that integrate are less likely churn.
○ Etc etc
16

17. “It’s time consuming”
● If you have any reason to think your company will be
successful, an API from the start will give you a leg up
against your competitors.
17

18. So what does
“API First”
mean?
18

19. Literally don’t build a user
interface until you have an API
19

20. Your API should be a bin of legos
● Break feature specs down only by what the
feature does, not what it looks like.
● When you add start mixing UI with behavior, your
application will have a hard time becoming a
platform for others to integrate with.
● When behavior is exposed via an API, actors
(internally or externally) can start imagining a UI
for themselves, and use the bricks provided to
execute.
20
API
User Interface

21. This doesn’t mean
building APIs blindly!
It’s a breakdown of how we build an end result
for customers
21

22. I’d wager 90% of companies build software this way
22
Product Planning
Write a story
(Clubhouse, Jira)
Engineering
builds feature
Ship it
Feature specification,
wireframes, acceptance
criteria, why we’re building
it
Iteration planning, team
assignment, “Given, When,
Then”
Take wireframes, design,
acceptance criteria, build
it
Deliver to customers,
announce, move on
Mixing UI + Behavior together
(This forces the need for full-stack engineers in many companies)

23. Subtle differences
You need to break this process down to be able
to build APIs first
23

24. 24
Feature Team Composition
Our Integrations Team
UX/UI Design
Frontend
Engineering
Product Manager
Backend
Engineering
SRE
(floating)

25. You need a design first (we use Figma)
25
Even a lo-fi, sharpie version works
UX/UI Design

26. That allows your team to discover
which APIs are needed
26
Product Manager
Backend
Engineering

27. This allows you to build an API first
27
The frontend work can be done async as well
Backend
Engineering

28. Then we have a fully functional frontend
28
Built by separate engineers, with separate pull requests
Frontend
Engineering
Backend
Engineering

29. Why is this better?
29

30. Building an API first is a forcing function
● This process would never work unless every person is on the same page.
● We’ve designed our feature teams to be tight-knit in order to ship backends
and frontends in async.
● This points everyone on the feature team in the same direction.
30

31. Building an API first is a forcing function
● It creates interfaces that your customers can now interface with.
● A platform that people can integrate with means tighter customer bonds.
● It generates conversations amongst the team that might not otherwise
happen.
31

32. Build for two
How to build an API that lasts
32

33. API Access
And why you should never
tie records to users
33

34. Actors
● While a user will make a request to your API
from your frontend, you must account for
other actors.
● Access to your API should not be restricted to
just user accounts.
● Build in authentication / authorization modes
that allow for both people and programs.
● Your underlying data model needs to change.
APIs are meant for computers
34
User Integration
Bot
Your API

35. Data model considerations
● Your data model needs to support the idea
of multiple actors creating and modifying
data.
● Most systems have a “god object”, User,
that everything has an association to.
○ This needs to change in order to build a
integratable platform.
○ You can use polymorphism or a single
entity with a type to achieve this.
35
Actors
User Integration
Bot

36. FireHydrant’s Data Model
36
Actors
User Integration
Bot
POST /v1/incidents
CREATE TABLE public.incidents (
id uuid DEFAULT public.gen_random_uuid () NOT NULL,
name character varying NOT NULL,
description text DEFAULT ''::text NOT NULL,
created_at timestamp without time zone NOT NULL,
updated_at timestamp without time zone NOT NULL,
status integer DEFAULT 0 NOT NULL,
created_by_type character varying,
created_by_id uuid,
organization_id uuid NOT NULL
);
Our database is heavily polymorphic,
allowing us to store multiple actor types
on records such as incidents.
This is a snippet of our incidents schema.
Declare an incident endpoint, which stores
who/what opened the incident

37. Alternative Data Model
37
Actor
User Bot Integration
Incident
Actor is associated to one of
user, bot, or integration
(polymorphic) and all other
records simply associate to a
single actor record
Runbook Etc...
(I wish we did this instead in hindsight)

38. What does this unlock?
● You can now separate types of actors in
your application with ease. Not
everyone is a “user”.
● If a data model associates everything to
a user via the API, what happens when
that person leaves the company?
○ Hint: All the integrations you built with
that users’ account break.
● All created via the same APIs your
frontend uses.
38
FireH
ydrant
U
ser
Slack
User

39. Allow for many
And constrain to one
39

40. Think two+ features ahead
40
● A golden rule I follow: It’s ok for an array to have one
element in it in your API.
● It’s common a mistake to restrict your JSON schema to a
singular object, and later on you need to add another.
● It’s much easier to constrain to one in code, but allow
for multiple in your database.

41. Story time
Where build for two would have saved
me a headache at Namely, an HR SaaS.
41

42. People can only report to one
person at a company right?
42

43. The dotted line reporting relationship is a weaker relationship. The dotted line
manager still has a formal right to some part of the individual’s time and attention
and will usually set some of goals. But it is not a strong relationship as a solid line.
Nope!
43

44. Simple JSON of the profiles
endpoint at Namely
44

45. What if we built for two...
45
● The JSON only supported one “reports_to” field even though the product now
supports multiple reports_to (with dotted line managers)
● This situation is the worst case scenario because JSON API’s can’t change
without heavy notice or complete deprecation
● This potentially could have been avoided if we thought two features ahead.

46. Reports to could be an array
46

47. What if we built for two...
47
● These opinions are mostly from putting my hand on a hot stove over the last
10 years
● Early decisions don’t always have to be “gotta go fast” mentality
● You can often build a model that will last you years if you think 2 features
away.
● IE: We have users now, but will we have companies? Will we have multiple
payment profiles?

48. Tools and tricks
To deliver great APIs
48

49. Document in tandem
● While you’re building your API, please,
oh please, document it as you go.
○ No one wants to go back and document
100+ endpoints.
● Use the OpenAPI specification (Swagger)
to quickly generate documentation.
● Use something that plugs into your
framework that can generate this
OpenAPI spec for you.
○ We use Grape + Grape Swagger.
49

50. Documentation Hosting
● There are a few options out there for
API documentation hosting. I personally
prefer stoplight.io
● They can read a OpenAPI specification
and generate nice documentation as
well as a “Try It” page for every endpoint.
● There are a few others out there as well.
50

51. APIs at
FireHydrant
A first class feature
51

52. It’s APIs all the way down
● All of our customers can access the
FireHydrant API that our UI does.
● This means our customers get the same
guarantees that our frontend gets, it’s
not an afterthought.
● OpenAPI spec allows us to generate
documentation websites and clients
with ease.
52
developers.firehydrant.io

53. Build an API first.
Future you will love you for it.
53

54. Thanks!
54
bobbytables bobbytables

55. 55
Stop by our booth in the
Expo for a chance to win
Airpods Max