JJ Geewax - API Design Patterns.pdf

JJ Geewax - API Design Patterns.pdf

《JJ Geewax - API Design Patterns.pdf》由会员分享，可在线阅读，更多相关《JJ Geewax - API Design Patterns.pdf（481页珍藏版）》请在冰豆网上搜索。

MANNINGJJGeewaxForewordbyJonSkeetTopicThistopiccovers.ResourceidentificationHowtoidentifyresourcesinanAPIStandardmethodsThesetofstandardmethodsforuseinresource-orientedAPIsPartialupdatesandretrievalsHowtointeractwithportionsofresourcesCustommethodsUsingcustom（non-standard）methodsinresource-orientedAPIsLong-runningoperationsHowtohandlemethodsthatarenotinstantaneousRerunnablejobsRunningrepeatedcustomfunctionalityinanAPISingletonsub-resourcesIsolatingportionsofresourcedataCrossreferencesHowtoreferenceotherresourcesinanAPIAssociationresourcesHowtomanagemany-to-manyrelationshipswithmetadataAddandremovecustommethodsHowtomanagemany-to-manyrelationshipswithoutmetadataPolymorphismDesigningresourceswithdynamically-typedattributesCopyandmoveDuplicatingandrelocatingresourcesinanAPIBatchoperationsExtendingmethodstoapplytogroupsofresourcesatomicallyCriteria-baseddeletionDeletingmultipleresourcesbasedonasetoffiltercriteriaAnonymouswritesIngestingunaddressabledataintoanAPIPaginationConsuminglargeamountsofdatainbite-sizedchunksFilteringLimitingresultsetsaccordingtoauser-specifiedfilterImportingandexportingMovingdataintooroutofanAPIbyinteractingdirectlywithastoragesystemVersioningandcompatibilityDefiningcompatibilityandstrategiesforversioningAPIsSoftdeletionMovingresourcestothe“APIrecyclebin”RequestdeduplicationPreventingduplicateworkduetonetworkinterruptionsinAPIsRequestvalidationAllowingAPImethodstobecalledin“safemode”ResourcerevisionsTrackingresourcechangehistoryRequestretrialAlgorithmsforsafelyretryingAPIrequestsRequestauthenticationVerifyingthatrequestsareauthenticanduntamperedwithAPIDesignPatternsAPIDesignPatternsJJGEEWAXFOREWORDBYJONSKEETMANNINGSHELTERISLANDForonlineinformationandorderingofthisandotherManningbooks,please.Thepublisheroffersdiscountsonthisbookwhenorderedinquantity.Formoreinformation,pleasecontactSpecialSalesDepartmentManningPublicationsCo.20BaldwinRoadPOBox761ShelterIsland,NY11964Email:

2021byManningPublicationsCo.Allrightsreserved.Nopartofthispublicationmaybereproduced,storedinaretrievalsystem,ortransmitted,inanyformorbymeanselectronic,mechanical,photocopying,orotherwise,withoutpriorwrittenpermissionofthepublisher.Manyofthedesignationsusedbymanufacturersandsellerstodistinguishtheirproductsareclaimedastrademarks.Wherethosedesignationsappearinthebook,andManningPublicationswasawareofatrademarkclaim,thedesignationshavebeenprintedininitialcapsorallcaps.Recognizingtheimportanceofpreservingwhathasbeenwritten,itisManningspolicytohavethebookswepublishprintedonacid-freepaper,andweexertourbesteffortstothatend.Recognizingalsoourresponsibilitytoconservetheresourcesofourplanet,Manningbooksareprintedonpaperthatisatleast15percentrecycledandprocessedwithouttheuseofelementalchlorine.Developmenteditor:

ChristinaTaylorTechnicaldevelopmenteditor:

AlKrinkerManningPublicationsCo.Revieweditor:

IvanMartinovic20BaldwinRoadProductioneditor:

DeirdreS.HiamPOBox761Copyeditor:

MicheleMitchellShelterIsland,NY11964Proofreader:

KeriHalesTechnicalproofreader:

KarstenStrbkTypesetter:

DennisDalinnikCoverdesigner:

MarijaTudorISBN:

9781617295850PrintedintheUnitedStatesofAmericaToKaiandLuca.Youareawesome.viibriefcontentsPART1INTRODUCTION.11IntroductiontoAPIs32IntroductiontoAPIdesignpatterns14PART2DESIGNPRINCIPLES.313Naming334Resourcescopeandhierarchy475Datatypesanddefaults65PART3FUNDAMENTALS.856Resourceidentification877Standardmethods1048Partialupdatesandretrievals1229Custommethods14110Long-runningoperations15411Rerunnablejobs175BRIEFCONTENTSviiiPART4RESOURCERELATIONSHIPS.18712Singletonsub-resources18913Crossreferences20014Associationresources20715Addandremovecustommethods21816Polymorphism225PART5COLLECTIVEOPERATIONS.23717Copyandmove23918Batchoperations25419Criteria-baseddeletion27020Anonymouswrites27821Pagination28522Filtering29923Importingandexporting313PART6SAFETYANDSECURITY.33324Versioningandcompatibility33525Softdeletion35726Requestdeduplication37127Requestvalidation38328Resourcerevisions39029Requestretrial40530Requestauthentication416ixcontentsforewordxxiprefacexxiiiacknowledgmentsxxvaboutthisbookxxviiabouttheauthorxxxiiiaboutthecoverillustrationxxxivPART1INTRODUCTION.11IntroductiontoAPIs31.1WhatarewebAPIs?

31.2WhydoAPIsmatter?

51.3Whatareresource-orientedAPIs?

61.4WhatmakesanAPI“good”?

8Operational9Expressive9Simple10Predictable122IntroductiontoAPIdesignpatterns142.1WhatareAPIdesignpatterns?

142.2WhyareAPIdesignpatternsimportant?

17CONTENTSx2.3AnatomyofanAPIdesignpattern19Nameandsynopsis19Motivation19Overview20Implementation21Trade-offs212.4Casestudy:

Twapi,aTwitter-likeAPI22Overview22Listingmessages23Exportingdata26PART2DESIGNPRINCIPLES.313Naming333.1Whydonamesmatter?

343.2Whatmakesaname“good”?

34Expressive35Simple35Predictable363.3Language,grammar,andsyntax36Language37Grammar37Syntax403.4Context413.5Datatypesandunits413.6Casestudy:

Whathappenswhenyouchoosebadnames?

433.7Exercises454Resourcescopeandhierarchy474.1Whatisresourcelayout?

48Typesofrelationships49Entityrelationshipdiagrams524.2Choosingtherightrelationship54Doyouneedarelationshipatall?

54Referencesorin-linedata55Hierarchy574.3Anti-patterns59Resourcesforeverything59Deephierarchies61In-lineeverything634.4Exercises645Datatypesanddefaults655.1Introductiontodatatypes66Missingvs.null675.2Booleans68CONTENTSxi5.3Numbers69Bounds70Defaultvalues71Serialization715.4Strings73Bounds73Defaultvalues74Serialization755.5Enumerations765.6Lists77Atomicity77Bounds78Defaultvalues795.7Maps79Bounds82Defaultvalues825.8Exercises82PART3FUNDAMENTALS.856Resourceidentification876.1Whatisanidentifier?

876.2Whatmakesagoodidentifier?

88Easytouse88Unique88Permanent89Fastandeasytogenerate89Unpredictable90Readable,shareable,andverifiable90Informationallydense916.3Whatdoesagoodidentifierlooklike?

91Datatype91Characterset92Identifierformat92Checksums93Resourcetype93Hierarchyanduniquenessscope946.4Implementation95Size95Generation96Tomb-stoning98Checksum98Databasestorage1006.5WhataboutUUIDs?

1016.6Exercises1027Standardmethods1047.1Motivation1057.2Overview1057.3Implementation106Whichmethodsshouldbesupported?

106Idempotenceandsideeffects107Get108List109Create112CONTENTSxiiUpdate114Delete115Replace116FinalAPIdefinition1187.4Trade-offs1207.5Exercises1208Partialupdatesandretrievals1228.1Motivation123Partialretrieval123Partialupdate1238.2Overview1258.3Implementation128Transport128Mapsandnestedinterfaces129Repeatedfields132Defaultvalues133Implicitfieldmasks135Updatingdynamicdatastructures136Invalidfields137FinalAPIdefinition1388.4Trade-offs138Universalsupport139Alternativeimplementations1398.5Exercises1409Custommethods1419.1Motivation142Whynotjuststandardmethods?

1429.2Overview1459.3Implementation146Sideeffects147Resourcesvs.collections147Statelesscustommethods149FinalAPIdefinition1519.4Trade-offs1529.5Exercises15210Long-runningoperations15410.1Motivation15510.2Overview15610.3Implementation158WhatdoesanLROlooklike?

159Resourcehierarchy160Resolution160Errorhandling164Monitoringprogress165Cancelingoperations167Pausingandresumingoperations168Exploringoperations169Persistence170FinalAPIdefinition172CONTENTSxiii10.4Trade-offs17310.5Exercises17411Rerunnablejobs17511.1Motivation17611.2Overview17611.3Implementation178Jobresources178Thecustomrunmethod180Jobexecutionresources181FinalAPIdefinition18411.4Trade-offs18611.5Exercises186PART4RESOURCERELATIONSHIPS.18712Singletonsub-resources18912.1Motivation189Whyshouldweuseasingletonsub-resource?

19012.2Overview19112.3Implementation192Standardmethods192Resetting195Hierarchy195FinalAPIdefinition19612.4Trade-offs197Atomicity198Exactlyonesub-resource19812.5Exercises19813Crossreferences20013.1Motivation20013.2Overview20113.3Implementation202Referencefieldname202Dataintegrity203Valuevs.reference204FinalAPIdefinition20613.4Trade-offs20613.5Exercises206CONTENTSxiv14Associationresources20714.1Motivation20714.2Overview208Associationaliasmethods20914.3Implementation210Namingtheassociationresource210Standardmethodbehavior210Uniqueness211Read-onlyfields211Associationaliasmethods212Referentialintegrity213FinalAPIdefinition21414.4Trade-offs216Complexity216Separationofassociations21614.5Exercises21615Addandremovecustommethods21815.1Motivation21915.2Overview21915.3Implementation220Listingassociatedresources220Dataintegrity221FinalAPIdefinition22215.4Trade-offs223Nonreciprocalrelationship223Relationshipmetadata22315.5Exercises22416Polymorphism22516.1Motivation22516.2Overview22616.3Implementation227Decidingwhentousepolymorphicresources227Polymorphicstructure228Polymorphicbehavior232Whynotpolymorphicmethods?

233FinalAPIdefinition23416.4Trade-offs23516.5Exercises235CONTENTSxvPART5COLLECTIVEOPERATIONS.23717Copyandmove23917.1Motivation24017.2Overview24017.3Implementation241Identifiers241Childresources244Relatedresources245Externaldata247Inheritedmetadata249Atomicity250FinalAPIdefinition25217.4Trade-offs25217.5Exercises25318Batchoperations25418.1Motivation25518.2Overview25518.3Implementation256Atomicity256Operationonthecollection257Orderingofresults258Commonfields258Operatingacrossparents259BatchGet261BatchDelete263BatchCreate264BatchUpdate265FinalAPIdefinition26618.4Trade-offs26918.5Exercises26919Criteria-baseddeletion27019.1Motivation27119.2Overview27119.3Implementation272Filteringresults272Validationonlybydefault274Resultcount275Resultsampleset275Consistency276FinalAPId