API Design on the Scale of Decades

151 Pages·2017·2.96 MB·English

API Design on the Scale of
Decades
Learn How to Architect and Design
Long-lasting APIs
Nordic APIs
©2016-2017NordicAPIs
Tweet This Book!
PleasehelpNordicAPIsbyspreadingthewordabout
thisbookonTwitter!
Thesuggestedtweetforthisbookis:
Checkout”APIDesignontheScaleofDecades”-the
latesteBookbythe@NordicAPIsteam
Thesuggestedhashtagforthisbookis#APIdesign.
Findoutwhatotherpeoplearesayingaboutthebookby
clickingonthislinktosearchforthishashtagonTwitter:
https://twitter.com/search?q=#APIdesign
Also By Nordic APIs
SummerCollection
DevelopingtheAPIMindset
WinterCollection
TheAPILifecycle
SecuringTheAPIStronghold
API-DrivenDevOps
TheAPIEconomy
ProgrammingAPIswiththeSparkWebFramework
HowtoSuccessfullyMarketanAPI
Thisbookisdedicatedtothespeakers,attendees,and
sponsorsthatcontinuallymakeNordicAPIsevents
wonderful!
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . i
APIsontheScaleofDecades . . . . . . . . . . . . i
DesigningaTrueRESTStateMachine . . . . . . . . 1
TheHistoryBehindRESTandHypermedia . . . . 2
HowdoweDefineREST? . . . . . . . . . . . . . . 3
Misconception#3:RESTAPIsShouldbeVersioned 6
Misconception #4: Hypermedia is Optional for
RESTAPIs . . . . . . . . . . . . . . . . . . . . 7
ExampleStateMachine:IoTToaster . . . . . . . 8
Conclusion . . . . . . . . . . . . . . . . . . . . . . 12
IsGraphQLTheEndofRESTStyleAPIs? . . . . . . 14
DefiningRESTanditsLimitations . . . . . . . . . 15
RoundTripandRepeatTripTimes . . . . . . . . 16
Over/UnderFetching . . . . . . . . . . . . . . . . 16
WeakTypingandPoorMetadata . . . . . . . . . 17
ImproperArchitectureUsage . . . . . . . . . . . 17
RESTHasManyRoundtrips-GraphQLHasFew . 19
REST Has Poor Type Systems - GraphQL Has a
SophisticatedOne . . . . . . . . . . . . . . . 19
REST Has Poor Discoverability - GraphQL Has
NativeSupport . . . . . . . . . . . . . . . . . 19
REST Is Thin Client/Fat Server - GraphQL is Fat
Client/FatServer . . . . . . . . . . . . . . . . 20
TheEndOfTheStatusQuo . . . . . . . . . . . . . 21
CONTENTS
Conclusion . . . . . . . . . . . . . . . . . . . . . . 22
ContinuousVersioningStrategyforInternalAPIs 23
TypicalPublicAPIVersioning . . . . . . . . . . . . 24
Badoo’sContinuousVersioningStrategies . . . . 26
ChangingtheVerificationProcess . . . . . . . . . 26
UpdatingBannerCTAsforSpecificClients . . . . 27
Use Flags to Avoid Versioning in Complex Busi-
nessLogicChanges . . . . . . . . . . . . . . 28
RunExperimentalFeatures . . . . . . . . . . . . . 28
HowContinuousVersioningCouldApplytoYou 28
CaseStudy:SpotifyInternalPaymentAPIs . . . . 30
TheEvolutionofSpotifyPayments . . . . . . . . 31
What’sReallyGoingonwithOnlinePayments? . 32
TheCheckoutAPI . . . . . . . . . . . . . . . . . . 33
TheBillingAPI . . . . . . . . . . . . . . . . . . . . 35
SampleUseCase:AutomaticAlerts . . . . . . . . 36
4ReasonsWhyAPIDesignisCriticaltoSubscrip-
tionServices . . . . . . . . . . . . . . . . . . 37
Analysis: Scalable API-Driven Infrastructure will
PowertheFutureofOnlinePayments . . . 39
TheBenefitsofaServerlessAPIBackend . . . . . 41
WhatDoes“Serverless”Mean? . . . . . . . . . . . 42
FromTraditionaltoServerlessEnvironments . . 43
HowGetStarted:UnderstandingtheServerless
Vendors . . . . . . . . . . . . . . . . . . . . . 45
DesigningEvent-DrivenServerlessApplications . 46
5ServerlessProTips: . . . . . . . . . . . . . . . . 47
Example:KickflipSDK . . . . . . . . . . . . . . . . 48
BuildingServerlessAPIBackends . . . . . . . . . 49
PuttinganEndtoAPIPolling . . . . . . . . . . . . . 51
WhatisthePollingMadness? . . . . . . . . . . . 52
OneSolution:RESTHooks . . . . . . . . . . . . . 53
CONTENTS
CounterArguments . . . . . . . . . . . . . . . . . 53
ImplementingRESTHooks . . . . . . . . . . . . . 54
Alternatives . . . . . . . . . . . . . . . . . . . . . . 56
Conclusion . . . . . . . . . . . . . . . . . . . . . . 57
6WaystoBecomeaMasterMicroserviceGardener 58
6 Ways to Become a Master Microservice Gar-
dener . . . . . . . . . . . . . . . . . . . . . . 59
1:UseBimodalITtoAvoidStagnation . . . . . . 60
2:AvoidtheKafka-esqueMonolith . . . . . . . . 61
3:DesignInaWayThatPromotesFurtherIteration 62
4:HarvestConceptsandIncorporate . . . . . . . 63
5: Distribute the Seeds: Adopt True Microser-
vicesArrangement. . . . . . . . . . . . . . . 63
6:PrunetheServiceSurface . . . . . . . . . . . . 64
NurtureAPIEcosystemGrowth . . . . . . . . . . 65
IsYourAPIAutomotiveGrade? . . . . . . . . . . . . 66
TestItLikeitHastobeAutomotiveGrade . . . . 67
AutomotiveGradeandFutureproofing . . . . . . 69
AutomotiveGradeandBackwardsCompatibility 70
FinalThoughts . . . . . . . . . . . . . . . . . . . . 71
WhyOAuth2.0IsVitaltoIoTSecurity . . . . . . . 73
WhatisOAuth2.0?. . . . . . . . . . . . . . . . . . 74
WhatDoesOAuthDo? . . . . . . . . . . . . . . . 75
UniqueIoTTraitsthatAffectSecurity . . . . . . . 76
ProofofPossession . . . . . . . . . . . . . . . . . 77
DisconnectedFlow . . . . . . . . . . . . . . . . . . 78
RealWorthAuthorizationFailure . . . . . . . . . 80
OAuthEmbedsTrustintotheIoT . . . . . . . . . 81
Conclusion . . . . . . . . . . . . . . . . . . . . . . 82
4DesignTweakstoImproveAPIOperations . . . 83
1:HTTPGETinsteadofPOST . . . . . . . . . . . . 84
2:LettingclientsconstantlypollAPIs . . . . . . . 85
CONTENTS
3:Rigidhierarchyinmicroservicescauseslatency 86
4:Genericactions . . . . . . . . . . . . . . . . . . 87
Harmon-iousMantrastoLiveBy . . . . . . . . . . 88
TheAPIofMe . . . . . . . . . . . . . . . . . . . . . . . 90
Confidential . . . . . . . . . . . . . . . . . . . . . . 91
Financial . . . . . . . . . . . . . . . . . . . . . . . . 93
Tactile . . . . . . . . . . . . . . . . . . . . . . . . . 94
Aggregate . . . . . . . . . . . . . . . . . . . . . . . 95
FinalThoughts . . . . . . . . . . . . . . . . . . . . 96
AvoidWalkingonEggshellsandUseDevOps . . . 98
SilosAreBadForBusiness . . . . . . . . . . . . . 99
KeyDevOpsConcepts . . . . . . . . . . . . . . . . 100
DevOpsandAPIs . . . . . . . . . . . . . . . . . . . 103
GuidestoAPIDevelopmentManagement . . . . 104
Conclusion:PuttingHumptyBackTogetherAgain107
SecuringtheIoTforDecadestoCome . . . . . . . 108
LookingintotheCrystalBall:TheWorldin2030 110
Identity is the #1 Impediment to Safe IoT Con-
nections . . . . . . . . . . . . . . . . . . . . . 111
Building on Open Standards will Secure Future
IdentityintheIoT . . . . . . . . . . . . . . . 111
TheNuancesofIoT-BasedCommunication . . . 114
5ActionableStepsTowardImprovingIoTSecurity114
5WaystheOpenAPISpecificationSpursAPIAgility116
WhatistheOpenAPISpecification? . . . . . . . . 117
WhyOpenAPISpecification? . . . . . . . . . . . . 118
APIFastness . . . . . . . . . . . . . . . . . . . . . 119
1:ProperDesignandApproach . . . . . . . . . . 119
2:CompleteDocumentationandDescription . . 120
3:RapidTestingandIteration . . . . . . . . . . . 121
4:Shorter(MoreSecure)TimetoMarket . . . . . 122
CONTENTS
5: Machine and Human Readability and Trans-
lation . . . . . . . . . . . . . . . . . . . . . . 123
Conclusion: OpenAPI Enables an Agile API Life-
cycle . . . . . . . . . . . . . . . . . . . . . . . 123
Case Study: Bosch Ongoing Enterprise API Man-
agementSaga . . . . . . . . . . . . . . . . . . . . 125
Isbuildingeverythingyourselfalwaystheanswer?126
Haveaneffectivestrategy . . . . . . . . . . . . . 127
Bereadyforthatstrategytofallapart . . . . . . 128
Thinkbig,evenwhenyou’resmall . . . . . . . . . 130
InSummary . . . . . . . . . . . . . . . . . . . . . . . . 132
TL/DR-15ImportantTakeaways . . . . . . . . . 132
What’sNext? . . . . . . . . . . . . . . . . . . . . . 134
NordicAPIsResources . . . . . . . . . . . . . . . . . 136
Endnotes . . . . . . . . . . . . . . . . . . . . . . . . . 139