throbber
Open in app 71
`
`e,, Medium Q Search
`
`( Sign up) Sign in
`
`0 Write
`
`Three Principles of API First Design
`
`When developing cloud-native applications, "API First" is a core
`principle. Putting that principle into practice is harder.
`
`Lars Trieloff • Follow
`, ~~ Published in Adobe Tech Blog • 4 min read • Jun 2, 2017
`
`6197 Q 4
`
`In my conversations with developers who are looking to embrace cloud(cid:173)
`native development and openness, one question frequently comes up: what
`exactly does ''API First" mean? All too often, ''API First" can come to mean
`"Yeah, APis are important, but they're not essential".
`
`There are three principles of API First Design:
`
`1. Your API is the first user interface of your
`application
`
`2. Your API comes first, then the implementation
`
`3. Your API is described (and maybe even self(cid:173)
`descriptive)
`
`GOOGLE 1045
`
`001
`
`

`

`Let’s take a look what each of these principles mean.
`
`  ÿ ÿÿ ÿ
` ÿ 
ÿ ÿ  ÿ
 ÿ 
`
`ÿ ÿ ÿ ÿ ÿ ÿÿÿ ÿ ÿ  
ÿ ÿ 
`
 ÿ ÿ ÿ ÿ ÿ  ÿ   ÿÿ ÿÿ
` ÿ ÿÿ ÿÿ ÿ ÿ ÿ  ÿ
` ÿ  ÿ ÿÿ
` ÿÿÿ
`ÿ ÿ 
ÿ   ÿÿ 
 ÿ ÿ ÿ  ÿ
` 
 ÿÿ ÿ 
ÿ ÿ
  ÿÿÿÿÿ
 ÿ ÿ
  ÿÿ
` 
ÿ ÿ  
ÿ
ÿ ÿ  
ÿ ÿ 
ÿ  
ÿ  
`
 ÿÿ ÿ 
 ÿ 
`!ÿÿ ÿÿÿ ÿ ÿÿ ÿ ÿ
`ÿ ÿ
ÿÿ 

`
`
` ÿ ÿ 
ÿ ÿÿ ÿ ÿ ÿ ÿÿ  ÿ   
`"#$%ÿ'$ÿ()#ÿ$*+,-ÿ%./+ÿ%)ÿ-+$.0,ÿ()#1ÿ01'*2.3'4ÿ#$+1ÿ.,%+15'3+6ÿ.,7+$%ÿ%./+
`%)ÿ-+$.0,ÿ()#1ÿ89:;ÿ
` ÿÿ   ÿ
` ÿÿ ÿÿ
`ÿÿ
`
`
`Finally, as your APIis the first and most important wayto access andinteract
`with your product, the API needs to be managed anddesigneddeliberately.
`Just as you spend timeto design yourgraphical user interface, invest time
`to design your API: what it exposes, what it does, and how it grows.
`
`APIfirst thinking meansthat your APIis the first interface of your
`applications. This meansthat the people developing against your API are
`your users, and your API needsto be designed with those users in mind.
`
`Your API is how yourproductexposesits functionality, so if there is
`functionality in your product not covered by an API, it can’t be covered by a
`graphical user interface, commandline interface, or voice interface either,
`effectively making the functionality invisible.
`
`002
`
`002
`
`

`

`Onceyourealize that your API is an interface that deservesattention of its
`own, you begin to realize that the API has — and should have —alife ofits
`
`own.
`
`Your implementation will change frequently, your API
`should not.
`
`
`  ÿÿ
`
ÿ  ÿÿÿ ÿ ÿ   ÿ  ÿ   ÿ  ÿÿ 
` ÿÿ  ÿ ÿ
`
ÿ  ÿ  ÿÿ ÿÿ ÿ
`ÿ  ÿÿ ÿ
`  ÿÿ 
` ÿ 
`   ÿ
`
`ÿ  ÿ ÿÿ 
`   ÿ 
` ÿ ÿ
` 
ÿ   ÿ ÿÿ  ÿ  
` ÿÿÿ  ÿ
`ÿ 
`  ÿ 
`ÿ ÿ  ÿÿ
`
`ÿ ÿ
`  
`
` !"#ÿ%&'()&)*+,+%!*ÿ-%((ÿ./,*0)ÿ1#)2")*+(34ÿ3!"#ÿ567
`8/!"(9ÿ*!+:
`;  <ÿ   ÿ ÿ ÿ  =ÿ  ÿ  ÿ  >ÿÿÿÿ ÿ  ÿ 
`
`  ÿÿÿ ?ÿ  ÿ  
` ÿ ÿ ÿ
` ÿ@
` ÿ 
`  
` ÿ
`
`ÿ
`ÿÿÿÿ  ÿÿABC
` <ÿ  ÿ ÿ  =ÿÿÿ 
`  ÿ ÿ ÿÿ ÿ ÿ   
`
` D 
` ÿE  
`ÿÿ 
`  ÿ ÿFGGHIHJKÿ ÿ ÿÿ  
` ÿ 
`
`Your implementation will change as your application evolves and you
`optimize, refactor and grow the functionality. Your API, however, should not
`change frequently, but instead grow slowly anddeliberately.
`
`Here’s another wayto think about this approach:If your APIis the surface
`area of your product; the functionality is its volume. Doubling the
`functionality will only grow your API surface by 25%.
`
`It’s important to think of API evolution in terms of growth and increasing
`flexibility. Graceful API evolution is additive in termsof functionality, and
`
`003
`
`003
`
`

`

`Treating your API as independent from the implementation, evenif that’s
`harder, allows you to decouple development of API and implementation.
`Your API becomesa contract and specification to the implementation,
`instead ofjust being a thin veneer on top of your implementation.
`
`subtractive in terms of requirements. While changeis inevitable, planning for
`a graceful API evolution is a good way to minimize changesthat break
`things. For example: required input may becomeoptional, but not the other
`way around.
`
`    ÿ
ÿÿÿ 
ÿ ÿ
ÿ ÿ
  ÿ!
ÿ
`ÿÿ"#$ÿ 
ÿ ÿÿ%ÿ&'ÿÿ
 (ÿ
ÿÿ)
`
ÿ*ÿ+!,ÿ %ÿ
!ÿ'ÿÿ! 
 ÿÿ
ÿÿ
`&'ÿ
%
`-
ÿ'ÿ"#$ÿÿ
%!
%
ÿÿÿ !
 
ÿ
ÿ ÿ.
`% ÿ&ÿ'ÿÿ%!ÿ%!
ÿÿ"#$ÿ
%ÿ !
 

`/ÿ"#$ÿÿÿ
ÿ
%ÿ!   
ÿÿÿ !
 

`
`
%ÿÿ0ÿ
ÿÿ
ÿ
ÿ
ÿ!ÿÿ'ÿ !
 

`
`-ÿ %ÿ!
 !ÿÿ"#$ÿ* ÿ1 
ÿ ÿÿ% ! 
ÿ$
ÿ%ÿ
`ÿ% ÿ'ÿ"#$ÿ
%ÿÿÿ 'ÿ
%%ÿ'ÿ!!ÿÿÿ
ÿ

`
`
%ÿ
ÿ ÿ 
ÿ-ÿ
ÿ%
 

`2ÿ"#$ÿ%
 
ÿ ÿ
ÿ
 ÿ!  ÿÿ)
ÿ 
`
ÿ'ÿ
ÿ"ÿÿ
%ÿ"$ÿ
.ÿ)
ÿÿ!

`
' ÿ
ÿ ÿ)ÿ ÿ
 
`
`The third principle of API First Design is about descriptiveness. In order to
`be used, your API needsto be easily understood by people that have not been
`involved in its creation. That means documentation.
`
`Usable API documentation is an essential prerequisite to makingit
`consumable by humans. As robots and AI aren't taking over programming
`anytime soon, this makesit essential.
`
`004
`
`004
`
`

`

`  ÿÿ 
`ÿÿ 
   ÿÿ
`ÿ
`

 ÿ 
   ÿ 
`
`

`

 ÿ 
   ÿ ÿ ÿ
`  ÿ  ÿÿ
`
`
`
ÿ
`ÿ

`ÿ  
`ÿ  
`ÿ

`ÿ  
`ÿ ÿ
`
`
` 
`ÿÿ ÿÿ
`ÿÿ!ÿ ÿ

` ÿ
 ÿ
`

`ÿ
`

`
`ÿ  ÿ
ÿÿ
`
`"  ÿÿ
`

`
`#ÿ ÿ
ÿÿ 
` ÿÿÿ   $ÿ
`

`
`ÿ
`ÿ
` 
`  ÿ
` 
`ÿ ÿ
`ÿ 
`ÿ %ÿ
`
`ÿ  ÿ&
`
` 
`
`ÿÿ ÿ
`ÿ 
 ÿ ÿ %  ÿ
`ÿ ÿ
ÿÿ
`

`
` &ÿ
`ÿ 

`ÿ
` ÿ ÿ
ÿ 
 ÿÿ ÿÿ ÿ
`ÿ  ÿ'

`ÿ
`ÿ  ÿ ÿ! 
`( ÿ
`ÿ ÿ  ÿ ÿ 
`ÿ% ÿ ÿ
`ÿ 
  ÿ
`ÿ
` ÿ
#
`)*+,ÿ./0.ÿ012ÿ,234562,7189.8:2ÿÿ

` ÿ    ÿ
`

`ÿ ÿ
`ÿ 
`
` ÿ ÿ 
`%ÿÿ ÿÿ
`

`ÿ( 
`ÿ%
`ÿ
ÿ ÿ ÿ ÿ
`
`ÿ ÿÿ ÿ 
` ÿ%ÿ     ÿÿ 
   
`;<==<>ÿ@ABÿCD<EBÿFBGAÿH=<IÿJ<KÿL<KBÿDBMB=<NBKÿO@<KPBOÿQRDÿKBO<SKGBOTÿQRDÿGABGUÿ<S@
`CD<EBÿVBMB=<NBKOÿ<RÿF>P@@BKÿJ<Kÿ@ABÿ=Q@BO@ÿRB>OÿQRDÿDBMB=<NBKÿNK<DSG@OW
`XYZ
`X[\ÿ^\_`a
`bcdefÿgh_i\jh`
`gdkalm_hÿnhihcd[ohpa
`
`005
`
`

`

`Written by Lars Trieloff
`4K Followers • Writer for Adobe Tech Blog
`
`Principal at Adobe
`
`More from Lars Trieloff and Adobe Tech Blog
`
`404 the strand
`
`I
`
`I
`
`~
`
`llllllD
`
`ECS
`
`•
`
`Lars Trieloff in Adobe Tech Blog
`
`•
`
`Neeraj Gupta in Adobe Tech Blog
`
`Testing Error Handling in node.js
`Four techniques I use to achieve consistently
`high test coverage and ensure my programs ...
`
`Deploy Microservices Using AWS
`ECS Fargate and API Gateway
`M icroservices are the key to design your
`application. In this post we will learn the way ...
`
`5 min read • Feb 18, 2019
`
`14 min read • Sep 7, 2020
`
`6117 Q
`
`6 503 Q 18
`
`006
`
`

`

`i
`
`Renae Kang in Adobe Tech Blog
`
`•
`
`Lars Trieloff
`
`Learnings From Project Caspian:
`Our Purpose-Built Security Data ...
`By Jericho Cain, Senior Staff Data Scientist,
`Hayden Beadles, Senior Security Machine ...
`
`Feature Function Benefit vs.
`Feature Advantage Benefit
`There are two basic popular frameworks for
`writing a marketing message: Feature-...
`
`3 min read • Nov 1
`
`6 1s 0
`
`5 min read • Jun 17, 2014
`
`6
`
`33 Q
`
`See all from Lars Trieloff
`
`See all from Adobe Tech Blog
`
`Recommended from Medium
`
`~
`
`i'"
`
`\..--.._ .........__
`
`"
`
`l,----
`
`007
`
`

`

`Ignacio de Gregorio
`
`Carlos Arguelles
`
`OpenAI Just Killed an Entire Market
`in 45 Minutes
`The Story Everyone Should Have Seen
`Coming
`+ · 6 min read • Nov9
`
`My favorite coding question to give
`candidates
`A coding question, from the viewpoint of an
`Google/Amazon/Microsoft interviewer
`
`10 min read • Nov 12
`
`6
`
`13.2K Q 184
`
`[:J
`
`6
`
`2.3K Q 33
`
`Lists
`
`t { ?6 •~
`.. General Coding Knowledge
`: 0 o -~ ~ ~:
`20 stories • 587 saves
`
`I Stories to Help You Grow as a
`
`Software Developer
`19 stories • 566 saves
`
`I
`
`ltocotll••w
`
`I -
`
`8 Charlie Steele in Klaviyo Engineering
`
`The Repository Pattern
`How we used the repository pattern to
`refactor a messy codebase
`
`Coding & Development
`11 stories • 276 saves
`
`Good Product Thinking
`11 stories • 347 saves
`
`{ JSON } is slow?
`
`...
`
`7111
`
`,.
`
`1, 1t•,.rq
`'
`
`I
`
`1'
`
`C \l •
`
`I
`
`Al te~natives?
`
`~ Vaishnav Manoj in DataX Journal
`
`JSON is incredibly slow: Here's
`What's Faster!
`Unlocking the Need for Speed: Optimizing
`JSON Performance for Lightning-Fast Apps ...
`
`14 min read • 6 days ago
`
`16 min read • Sep 28
`
`008
`
`

`

`6 313 Q 2
`
`6 9.5K Q 121
`
`0 KostyaStepanov in UX Planet
`
`f) Raphael Moutard
`
`Back-End & Web Development
`Trends For 2024
`By Mary Moore, copywriter at Shakuro
`
`Forget your Microservices! The
`Unparalleled Benefits of Pool ...
`When monoliths are the solution to your
`scaling challenges.
`
`9 min read • Oct 17
`
`6 559 Q 10
`
`6 min read • Nov 5
`
`6 499 Q 16
`
`See more recommendations
`
`009
`
`

This document is available on Docket Alarm but you must sign up to view it.


Or .

Accessing this document will incur an additional charge of $.

After purchase, you can access this document again without charge.

Accept $ Charge
throbber

Still Working On It

This document is taking longer than usual to download. This can happen if we need to contact the court directly to obtain the document and their servers are running slowly.

Give it another minute or two to complete, and then try the refresh button.

throbber

A few More Minutes ... Still Working

It can take up to 5 minutes for us to download a document if the court servers are running slowly.

Thank you for your continued patience.

This document could not be displayed.

We could not find this document within its docket. Please go back to the docket page and check the link. If that does not work, go back to the docket and refresh it to pull the newest information.

Your account does not support viewing this document.

You need a Paid Account to view this document. Click here to change your account type.

Your account does not support viewing this document.

Set your membership status to view this document.

With a Docket Alarm membership, you'll get a whole lot more, including:

  • Up-to-date information for this case.
  • Email alerts whenever there is an update.
  • Full text search for other cases.
  • Get email alerts whenever a new case matches your search.

Become a Member

One Moment Please

The filing “” is large (MB) and is being downloaded.

Please refresh this page in a few minutes to see if the filing has been downloaded. The filing will also be emailed to you when the download completes.

Your document is on its way!

If you do not receive the document in five minutes, contact support at support@docketalarm.com.

Sealed Document

We are unable to display this document, it may be under a court ordered seal.

If you have proper credentials to access the file, you may proceed directly to the court's system using your government issued username and password.


Access Government Site

We are redirecting you
to a mobile optimized page.





Document Unreadable or Corrupt

Refresh this Document
Go to the Docket

We are unable to display this document.

Refresh this Document
Go to the Docket