`
`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.
`
` ÿ
`ÿÿ"#$ÿ
`
`&'ÿ
`-
`% ÿ&ÿ'ÿÿ%!ÿ%!
`/ÿ"#$ÿÿÿ
`
`
`
`-ÿ%ÿ!
`ÿ% ÿ'ÿ"#$ÿ
`
`
`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
`
`