APIProvidersGuideAPIDesignPreparedByKinLane

June2014

Table of ContentsOverviewofTheAPIDesignSpaceANewGenerationOfAPIDesignDevelopingTheLanguageWeNeedToCommunicateLeadingAPIDefinitionFormatsBuildingBlocksofAPIDesignCompaniesWhoProvideAPIDesignServicesAPIDesignToolsAPIDesignEditorsAPIDefinitionsProvidingACentralTruthForTheAPILifecycleContributingToTheDeploymentLifecycleContributingToTheManagementLifecycleContributingToTheTesting&MonitoringLifecycleContributingToTheDiscoveryLifecycleAnEvolutionaryPeriodForAPIDesign

Overview of The API Design SpaceIntheearlydaysofAPIs,everythingwasjustaboutdeployingandconsumingyouweredoingoneortheother.Thenby2006wesawthestabilizationofcommonAPImanagementpracticesemergefromproviderslikeMashery,andthen3Scale.Nowin2014wearestabilizingagain,andtheAPIuniverseisexpandingaroundtheareaofAPIdesign,withnewapproaches,toolsandentirecompaniesemergingtoprovideservicesthatarededicatedtohelpingcompaniesdesignthebestAPIstheycan.

IdefinetheworldofAPIdesignaseverythingthatgoesintoplanninganddesigningyourAPI,aswellasthedefinitionofyourAPIthatwilleventuallybedeployedasyourproductionendpoints,driveyourdocumentation,generatethecodesamplesyourdeveloperswillusetointegrate,test,monitor,andallowyourAPItobefoundthroughthislens,APIdesignisfastbecomingthedriverforallareasoftheAPIlifecycle.

Dependingonourneeds,APIdesignmaybeginwithunderstandingHTTP,andREST,ormaylearningmoreaboutapplyinghypermediaaspartofyourdesignconstraints,orAPIdesignmightsimplybeaboutgeneratingaSwaggerdefinition,soyoucangenerateinteractiveAPIdocumentation.IwontbegoingintothefinerpointsofREST,HypermediaorevenSwaggerdefinitions.Mygoalistoprovidea100Kviewofspace,andhighlightthevarioustools,services,andAPIdesignmethodologiesavailabletoday.

UltimatelyyourAPIdesignwillbethedefinitionofeachendpoint,itsmethods,fieldsandmuchmore.InatechnicalsenseitisaJSON,YAMLormarkdownblueprintthatdescribesyourAPI,andinacreativesense,APIdesignisanartthatcanpossessastrangetechnicalbeauty,andspeaktothevalueanAPIdeliverstoendusers.APIdesignisfarmorethanjusthowyoustructureURIs,orparameters,itisfastbecomingadiscipline,withasuiteofservicesandtoolstosupportagrowingwaveofAPIdesignprofessionals.

ThoughtfulAPIdesignearlyoncansaveyoualotofmistakesdowntheroad.Thisprojectisnotmeanttoendorseanyparticularapproachormethodology,butprovideasingleresourcewhereyoucanfindthebestinformationonAPIdesign,andgotheretofindwhatyouneed.Itcanbedifficulttostayupwiththelatesttools,andapproaches,andAPIEvangelistlookstofillthisgap.

ThisAPIdesignprojectwillliveasanopensourcerepository,andresultingwhitepapercontainingthebuildingblocksofAPIdesign,toolsthatassistyouinyourAPIdesign,andcompaniesthatprovideservicesintheareaofAPIdesign.

Thisisalivingproject,thatwillbeupdatedasIhavetime..Ifyouknowofmissingbuildingblocks,ortoolsandservicesthatshouldbeincluded,sendthemtoinfo@apievangelist.com

A New Generation Of API DesignThisisnotastoryofWSDLorevenWADL,thisnarrativebeingsinearly2011withthereleaseofanewWordnikdeveloperarea,whichincludedanewversionoftheAPIdocumentation,thatwasntjustthesameoldstaticAPIdocsthistimeitwasbeingdrivenbyanewAPIdefinitionformat,thatTonyTamfromWordnikwouldlatercallSwagger.Wordnikneededawaytokeeptheirdocumentationuptodate,sotheycreatedSwagger,aJSONformatfordescribingtheWordnikAPI,andthenbuiltSwaggerUI,anautomaticallygenerated,interactivedocumentationfortheAPI.

Withthisonerelease,SwaggerwouldusherinanewgenerationofAPIdesign,givingusanewwaytodescribetheincreasingnumberofAPIsweweredeveloping,andallowustoautomaticallydeliver,interactivedocumentationthatwouldhelpconsumersunderstandthevalueanAPIdelivers.Wordnikdidn'tstopthere,theycreatedtoolingforgeneratingserversideandclientsidecode,directlyfromthesameSwaggerAPIdefinitions.

WordnikhaddevelopedSwaggertomeettheirownneedsarounddesigningandmaintaingtheWordnikAPI,butthroughthisprocess,theyalsosetthestageforanewwaytodefineourAPIs,thatwouldgiveusaacommon,machinereadablelanguagefordiscussingandcollaboratingaroundourAPIs,generatingcode,documentation,andastimewouldshow,much,muchmore.

Developing The Language We Need To CommunicateWearestillintheinfancyoftheAPIeconomy,andnowwithbarely14yearsofwebAPIdesignevolution,weareonlynowjustdevelopingthelanguageswewillneedtocommunicatearoundAPIsthroughouttheirlifecycle,fromthefirstmockoftheAPIresource,tomonitoringofaproductionAPIinthewild,ormakingavailabletoanewbreedofAPIsearchengines.

TherehaslongbeenstandardsfordescribingAPIs,suchasWSDLforSOAP,andWADLforwebAPIs,buttheseformatswouldneveractuallyenablethemeaningfulinteractionsaroundAPIsthatitwouldtaketoachievewidespreadsupport.WSDLwastooprogrammatic,andheavyhanded,whileWADLneverpossessedtheincentivesAPIprovidersneeded,totakethetimetodefinetheirAPIsusingtheheavyXMLformat.

Itwasn'tuntilearly2011,wewouldseethefirstsignsofameaningfullanguagefordescribingwebAPIs,thatwouldenableustohaveproductiveconversations,andtakeactionaroundourAPIdesigns.InFebruary2011,onlinewordmeaninganddefinitionsiteWordnik,launchedanewAPIdeveloperportal,completewithanewwaytodocumentAPIs,thatwasinteractive,andalloweddeveloperstomakeliveAPIcalls,whilelearningaboutwhatanAPIoffered.InanefforttokeeptheirAPIdocumentationuptodate,WordnikalsoestablishedanewwaytonotjustdocumentandcommunicatewithanAPI,butallowustoactuallyhaveasharedconversationabouttheactualdesignoftheAPIitselfchangingwhatAPIdesignmeant.

Lateronthatyear,APImanagementproviderMasherywouldemulateWordnik'sapproach,andlaunchedtheirI/ODocs.Immediatelyafter,inAugust2011,WordnikformallylaunchedtheirapproachtodefiningAPIs,generateinteractivedocumentation,andserverorclientsidecodewhichtheycalledSwagger.OverthenexttwoyearstheSwaggerecosystemwouldgrowandevolve,producingnewversions,tooling,andimplementationsofbothprivateandpublicAPIimplementations.

Duringthistime,theconceptofAPIdesignwouldexpand,withtechgiantslikeGoogleestablishingtheirownapproach,whichtheycalledGoogleDiscovery,andwewouldseeanewbreedofAPIdesignserviceprovidersemergewithApiary.io.ByMarch2013,ApiaryhadlaunchedtheirownAPIdefinitionformatcalledAPIBlueprint,whichallowedAPIproviderstodefineanAPIusingmarkdown,anditerateonthedesignusingApiary.ioservices.ApiaryhadmovedtheincentivesfordefiningAPIsasamachinereadableformat,earlieroninthelifecycle.Nowwedidn'tjustgeneratemachinereadabledefinitionstodeployservercode,orgenerateinteractivedocsandclientsidecode,wewoulddoitbeforeweactuallydeployedtheAPI,allowingustomockourAPIdesigns,andcollaboratearounddesigningtheactualAPI,priortodeployment.

Thenbytheendof2013,we'dseeanotherAPIdefinitionlanguageemerge,thistimefromenterprisetechnologyproviderMulesoft,calledRAML.ThisnewapproachtodefiningAPIs,woulduseYAMLtoproduceamachinereadable,yethumanfriendlywaytodescribeAPIs.NowwehadfourwaystodescribeourAPIs,andaswepushinto2014,wealsohaveawealthoftooling,services,andaselectionofmaturingAPIdesigneditorstochoosefromwhenplanninganddesigningourAPIs.

Ifeellikewearejustmovingfrominfancy,intothetoddlerphaseofcommunicatingthroughoutthewebAPIlifecycle.Wenowhaveseverallanguagestochoosefrom,wejusthavetoworkhardtoeducatepeoplethattheyexist,assist

thembecomefluentwiththeirchosenformat,andexpandtheincentivesforgeneratingmachinereadabledefinitionsforourAPIs.

Leading API Definition FormatsInthelastcoupleyears,we'veseenanemergenceoffournewmachinereadableformats,thatgiveusanewwaytodescribeAPIs,aswellasinteractwithothersthroughouttheAPIslifecycle.TheemergingformatsuseJSON,Markdown,andYAMLtodefineanAPI,providingasimple,machinereadableblueprint,thatAPIprovidersandconsumerscanuseasingletruthforallAPIinteractions.

I'malsolookingatotherformatsI'vecomeacrossinthespace,andwillbeaddingthemtomylistasIbetterunderstandthem,andabletoquanitytheirreach.FornowI'llbetrackingonthefourleadingAPIdefinitionformats.

Swagger

ThegoalofSwaggeristodefineastandard,languageagnosticinterfacetoRESTAPIswhichallowsbothhumansandcomputerstodiscoverandunderstandthecapabilitiesoftheservicewithoutaccesstosourcecode,documentation,orthroughnetworktrafficinspection.WhenproperlydefinedviaSwagger,aconsumercanunderstandandinteractwiththeremoteservicewithaminimalamountofimplementationlogic.Similartowhatinterfaceshavedoneforlowerlevelprogramming,Swagerremovestheguessworkincallingtheservice.

APIBlueprint

APIBlueprintisadocumentationorientedAPIdescriptionlanguage.AcoupleofsemanticalassumptionsovertheplainMarkdown.APIBlueprintisperfectfordesigningyourWebAPIanditscomprehensivedocumentationbutalsoforquickprototypingandcollaboration.Itiseasytolearnandeveneasiertoreadafterallitisjustaformofplaintext.APIBlueprint,itsparser,andmostofitstoolsarecompletelyopensourcedsoyoudon'thavetoworryaboutvendorlockin.ThisalsomeansyoucanfreelyintegrateAPIBlueprintintoanytypeofproduct,commercialornot.

RAML

RESTfulAPIModelingLanguage(RAML)isasimpleandsuccinctwayofdescribingpracticallyRESTfulAPIs.Itencouragesreuse,enablesdiscoveryandpatternsharing,andaimsformeritbasedemergenceofbestpractices.ThegoalistohelpourcurrentAPIecosystembysolvingimmediateproblemsandthenencourageeverbetterAPIpatterns.RAMLisbuiltonbroadlyusedstandardssuchasYAMLandJSONandisanonproprietary,vendorneutralopenspec.

MasheryI/ODocs

I/ODocsisaliveinteractivedocumentationsystemforRESTfulwebAPIs.BydefiningAPIsattheresource,methodandparameterlevelsinaJSONschema,I/ODocswillgenerateaJavaScriptclientinterface.APIcallscanbeexecutedfromthisinterface,whicharethenproxiedthroughtheI/ODocsserverwithpayloaddatacleanlyformatted(prettyprintedifJSONorXML).BasicHTMLtexttagsareenabledintheJSONschema.

Building Blocks of API DesignWhenIlookatallofthecurrentcompanieswhoaredevelopingservicesandtoolsfortheAPIdesignspace,Ibegintoseecertainbuildingblocksemerge,providingakindofcommonblueprintforquantityingtheworldofAPIdesign.Mygoalistohelpunderstandwhatfeatures,tools,andservicesthesecompaniesaredelivering,butalsowhichonesAPIdesignersaredemandingandactuallyputtingtouse.

Thegoalofthisresearch,istoidentifycommonbuildingblocksthatcanhelpnew,aswellasadvancedAPIproviders,understandthedifferentapproachestoAPIdesign,whilenotmakinganyassumptiononwhichisbest,justshedlightonwhatisavailable,andmaybealookintotheprosandcons,andhoweachofthesolutionsfitintothebiggerworldofAPIdesign.

BuildingblocksareaboutassemblingAPIdesignconceptsintomodular,bitsizechunks,inanefforttoeducateandprepareyou,foryourownAPIdesignefforts.KeepinginlinewithwhereIseeAPIdesignheaded,mylistofbuildingblocks,naturallysstartswithmachinereadableAPIdefinitions.

Definition

Acentral,machinereadabledefinitionofanAPIinterface,authenticationandpotentiallydatamodel,inXML,JSONorMarkdown.(Examples:APIBlueprint,RAML,Swagger)

Parser

AnAPIdefinitionparser,availablepotentiallyinmultiplelanguagesandopenuptheprogrammaticgenerationofotherAPIbuildingblocks.

DesignTools

Userinterfacetools,allowingforthebuildingofcentralAPIdefinitions,eitherinacodevieworGUIview.

Versioning

SystemsallowingfortheversioningofAPIdefinition,keepingtrackofallchanges,allowingforrollingbackofchangestopreviousversions.

Forkable

TheabilitytoforkanexistingAPIdefinition,andcreateanewbranch,thatcanliveseparatelyfromtheAPIdefinitionitoriginatesfrom.

Sharing

AllowingforthesharingofAPIdefinitionsandotherAPIdesignbuildingblockswithotherusers,employingcommonsocialsharingfeaturesofpreferrednetworks.

Collaboration

Featuresthatallowforcollaborationbetweenusers,withdiscussionaroundallAPIdesignbuildingblocks.

MockInterfaces

AbilitytodeploymockAPIinterfacesgeneratedfromAPIdefinitions,allowingdeveloperstoplaywithAPIversionsastheyaredesigned.

InteractiveDocumentation/Console

AutomaticallygeneratedAPIdocumentationwhichallowsdeveloperstomakecallsagainstAPIsastheyarelearningabouttheinterface,turningAPIeducationintoahandsonexperience.

Notebook/Directory

Alocal,orcloudbasedstoragerepository,providingasingleplacetocreateandmanageAPIdefinitions,andexecuteotherAPIdesignbuildingblocks.

Testing

Manual,automatedandscheduledtestingofAPIinterfacesusingtheirAPIdefinitionasablueprint,allowingdeveloperstotestallAPIstomakesuretheycomplytoAPIdefinition.

Debugging

Manual,automatedandscheduleddebuggingofAPIinterfaces,providingdetailedlookinsideofAPIcalls,allowingdeveloperstounderstandproblemswithAPIintegrations.

TrafficInspection

LoggingandanalysisofAPItrafficfromtesting,debuggingandallotherAPIusageduringtheAPIdesignprocess.

Validator

ToolsforvalidatingAPIcalls,enablingdeveloperstodeterminewhichtypesofcallswillbevalid,usingcentralAPIdefinition.

ServerCodeGenerators

ToolingthatgeneratesserversideimplementationsusingAPIdefinitionsinavarietyoflanguages.

ClientSideCodeGenerator

ToolingthatgeneratesclientsideAPIcodelibrariesinavarietyoflanguages.

GithubSync

TheabilitytostoreandsyncAPIdefinitionswithGithub,providingacentralpublicorprivaterepositoryforthedefinitionofanAPIresource.

CommandLine

CommandlinetoolingforexecutionofallAPIbuildingblocks.

Websockets

ProvidingtoolsforAPIcommunicationviawebsocketsusingAPIdefinitionasaguide.

Translator

ToolsfortranslatingbetweenvariousAPIdefinitions,allowingthetransformationfromRAMLtoSwagger,andbetweeneachAPIdefinitionformat.

Annotation

ToolsandinterfacesforallowingtheannotationofAPIdefinitions,providingacommunicationplatformcenteredaroundtheAPIdesignprocess.

SyntaxHighlight

ToolsandinterfacesforthehighlightingofAPIdefinitions,providingIDElikefunctionallyforAPIdesigners.

Companies Who Provide API Design ServicesMostAPIdesignworkisdonebycompaniesinsupportoftheirownAPIprograms,butasthespaceexpandstherearenewcompaniesemerging,providinguswithnewtools,services,andapproahcesspecificallydedicatedtoAPIdesign.I'mworkingtokeeptrackofthesecompanies,andunderstandhowtheyareinfluencingthespaceherearethefourI'mcurrentlytrackingon.

https://apiary.io

http://blog.apiary.io/

http://blog.apiary.io/feed.xml

https://twitter.com/apiaryio

https://github.com/apiaryio

http://crunchbase.com/company/apiary

Apiary.io

Apiary.ioisahostedsuiteoftoolsthathelpcompaniesbuildwebAPIsquickly,test&monitorthemeasilyanddocumentthemeffortlessly.ItprovidesAPIownerswithnecessaryinfrastructureandhelpsthembuildrelationshipwiththeirusers.CoreoftheselfservicesolutionisAPIBlueprint,anefficientformatfordescribinganAPI,aspiringtodefinenewgoldstandardforRESTAPIdevelopment.TheproductusesthisBlueprinttostreamlineadoptionofnewservicesandsimplifyintegrationtoothersystems.

http://mashery.com

http://www.mashery.com/blog

http://feeds.feedburner.com/MasheryBlog

https://twitter.com/Mashery

https://github.com/mashery

http://crunchbase.com/company/mashery

Mashery

MasherysAPImanagementtoolsandstrategicserviceshelpcompaniesconnectwithcustomersandpartnersinachangingdigitalworldbyextendingreachacrossdevices,marketsandtheWeb.MasheryleadstheindustrywithaholisticapproachforAPIinitiativesfromsettingplatformstrategyandmeasuringbusinessobjectivestotheheavyliftingofprovidingandmanaginginfrastructuretofacilitatingrelationshipswithour150,000strongnetworkofWebandmobileapplicationdevelopers.Havingworkedwithover100leadingbrandstopowermorethan40,000apps,Masherysknowledge,experienceandprovenstrategiesenablecompaniestofocusontheircorebusinesswhiledrivingsales,buildingnewrevenuechannelsandrealizingfastertimetomarketforinnovativeapplications.

http://www.mulesoft.com/

http://blogs.mulesoft.org/

http://feeds.feedburner.com/muleblog

https://twitter.com/MuleSoft

MuleSoft

MuleSoftprovidesthemostwidelyusedintegrationplatformforconnectingSaaSandenterpriseapplicationsinthecloudandonpremise.Withtheriseofcloudandmobile,enterprisesfaceachoice:getoverwhelmedbytheresultingexplosionofendpointsorseizetheopportunitytogaincompetitiveadvantage.Foundedontheideathatconnectingapplicationsshouldnotbehard,MuleSoftletsorganizationsharnessthepoweroftheirapplicationsthroughintegration.MuleSoftsAnypointtechnologyeliminatescostly,timeintensivepointtopointintegration,enablingbusinessagility.Deliveredasapackagedintegrationexperience,CloudHubandMuleESB(EnterpriseServiceBus)arebuiltonprovenopensourcetechnologyforthefastest,mostreliableonpremiseandcloudintegrationwithoutvendorlockin.

http://swagger.wordnik.com/

https://github.com/Swagger

Swagger

SwaggerUIispartofSwaggerproject.TheSwaggerprojectallowsyoutoproduce,visualizeandconsumeyourOWNRESTfulservices.Noproxyor3rdpartyservicesrequired.Doityourownway.SwaggerUIisadependencyfreecollectionofHTML,Javascript,andCSSassetsthatdynamicallygeneratebeautifuldocumentationandsandboxfromaSwaggercompliantAPI.BecauseSwaggerUIhasnodependencies,youcanhostitinanyserverenvironment,oronyourlocalmachine.

API Design ToolsTherearemanynewtoolsemergingfromtheAPIdesignworkgoingonacrosstheAPIsectorin2014.Rightnow,manyoftheseAPItoolsseemtobefocusedongeneratingAPIdefinitionsinvariousformats,includingJSON,YAMLandMarkdown,withafocusonAPIdeployment,manageent,andmorerecentlyintegrationanddiscovery.

Generallythesetoolsareopensourcerepositories,thatarestoredatGithub.Mygoalistoempoweryou,theAPIproviderorconsumer,withtheresourceyouwillneetogrowandevolveyourAPIdesignstrategy.

ItendtoorganizeanyinterestingtoolsIfindunderasingleumbrella,butasIstarttoseecommonpatterns,IwillbreakthemoutintoseparategroupssuchaswiththeAPIdesigneditorslistedbelow.

ALPSApplicationLevelProfileSemantics

http://amundsen.com/hypermedia/profiles/

ThepurposeofApplicationLevelProfileSemantics(ALPS)istodocumenttheapplicationlevelsemanticsofaparticularimplementation.Thisisaccomplishedbydescribingelementsofresponserepresentationsforatargetmediatype.Forexampleidentifyingmarkupelementsreturned(i.e.semanticHTMLalaMicroformats)andstatetransitions(i.e.HTML.AandHTML.FORMelements)thatadvancethestateofthecurrentapplication.

AtomEditorAPIBlueprintPreview

https://atom.io/packages/apiblueprintpreview

ApluginfortheAtomeditortoshowtherenderedHTMLAPIBlueprinttotherightofthecurrenteditorusingctrlshifta.

RAMLAPIDesigner

https://github.com/mulesoft/apidesigner

APIDesignerisawebbasedAPIdevelopmenttoolthatallowsAPIproviderstodesigntheirAPIquickly,efficiently,andconsistently,andsocializethedesign.ItconsistsofaRAMLeditorsidebysidewithanembeddedRAMLconsole(theAPIConsole).ItisprovidedundertheopensourceCPALlicense.

RAMLAPINotebook

https://github.com/mulesoft/apinotebook

APINotebookisawebbased,persistent,JavaScriptscriptingworkspacethat

enableslivetestingandexploringofAPIs,andsavingAPIusecasesasmarkdowngists,sotheyareversioned,forkableandshareable.It'sanexampleofliterateprogramming.ItisprovidedundertheopensourceCPALlicense.

RAMLStore

https://github.com/brianmc/ramlstore

RAMLStoreprovidesasimplestorageAPIplusapersistencepluginwhichenablesyoutoruntheRAMLAPIDesignerlocally(ratherthanusingacloudservice)andstillbeabletomanageandcollaborateonyourdesign.Theserviceisbuiltwithnode.js,usingexpressandmongodb.

RspecAPIBlueprint

https://github.com/playround/rspec_api_blueprint

AutogenerationofAPIdocumentationusingtheBlueprintformatfromrequestspecs.

SwaggerEditor

http://editor.swagger.wordnik.com/

SwaggerEditorletsyoueditAPIspecificationsinYAMLinsideyourbrowserandtopreviewdocumentationsinrealtime.ValidSwaggerJSONdescriptionscanthenbegeneratedandusedwiththefullSwaggertooling(codegeneration,documentation,etc).

Swagger2RAML

https://github.com/8x8Cloud/swagger2raml

AutilitytogenerateRAMLdocumentationfromSwaggerJSON.

API Design EditorsListedaboveintoolsyouwillfindtwoopensourceAPIdesigneditors,fromRAMLandSwagger.I'dliketobreakoutAPIdesigneditorsintoitsowngrouping,becauseIfeelthisasignificantareaofgrowthintheAPIdesignspaceoverthelastyear,andwillcontinuetobeafocalpointfortheevolutionofAPIdesign.

ThefirstAPIdesigneditorwasasaservice,fromApiary.io,butlastyearwealsosawtherolloutoftheRAMLAPIDesigner,andthislastmonthSwaggerrolledouttheirowneditor,designedaroundtheSwaggerspecification.

Apiary.io

https://apiary.io

Apiary.ioisahostedsuiteoftoolsthathelpcompaniesbuildwebAPIsquickly,test&monitorthemeasilyanddocumentthemeffortlessly.ItprovidesAPIownerswithnecessaryinfrastructureandhelpsthembuildrelationshipwiththeirusers.CoreoftheselfservicesolutionisAPIBlueprint,anefficientformatfordescribinganAPI,aspiringtodefinenewgoldstandardforRESTAPIdevelopment.TheproductusesthisBlueprinttostreamlineadoptionofnewservicesandsimplifyintegrationtoothersystems.

RAMLAPIDesigner

https://github.com/mulesoft/apidesigner

APIDesignerisawebbasedAPIdevelopmenttoolthatallowsAPIproviderstodesigntheirAPIquickly,efficiently,andconsistently,andsocializethedesign.ItconsistsofaRAMLeditorsidebysidewithanembeddedRAMLconsole(theAPIConsole).ItisprovidedundertheopensourceCPALlicense.

SwaggerEditor

http://editor.swagger.wordnik.com/

SwaggerEditorletsyoueditAPIspecificationsinYAMLinsideyourbrowserandtopreviewdocumentationsinrealtime.ValidSwaggerJSONdescriptionscanthenbegeneratedandusedwiththefullSwaggertooling(codegeneration,documentation,etc).

API Definitions Providing A Central Truth For The API LifecycleAsthesenewwaysofcommunicatingaroundAPIsemerge,andevolve,theyareprovidinguswithasingledefinitionofanAPI,thatcanbeappliedasasortoftruth,throughallstagesoftheAPI'slifecycle.

WhilemachinereadableAPIdefinitionsmaynotdeliveronautomatingallaspectsoftheAPIlifecycle(assomeenvision),itdoesprovideasetofguidingprinciples,actingasatruthwhenmocking,deploying,generatingcode,testing,monitoring,producingdocumentationandotherAPIcontent.

TherecentAPIdesigneraweareinwaskickedoffbythedesiretogenerateinteractivedocumentation,butin2014weareseeingmorereasonsforgeneratingmachinereadableAPIdefinitions,andusingthemasaguidethroughouttheAPIlifecycle.

BeyondasingledefinitionthatcanbeusedthroughoutasingleAPIslifecycle,bytheAPIprovider,APIdefinitionsalsoallowforopeningupaconversationexternallywithAPIconsumers,andother3rdpartydevelopers,usingacommonlanguageandsyntaxestablishingapotentiallysharedmeaningaroundwhatanAPIdelivers,internallyandexternally.

ThesinglemostimportantthingthatmachinereadableAPIdefinitiosnprovide,istheabilitytosharesuccessful,orcommonAPIblueprintswiththewiderAPIsector,orjustwithinaspecificindustry.AcatalogofwelldesignedAPIblueprints,thatAPIproviderscanuse,haslongbeenadeficiencyacrosstheAPIspaceAPIdefinitionsprovideatruth,allowingfortheestablishment,sharingandreuseofthebestAPIpatternsavailable,allowingustonotreinventthewheelwitheveryAPIincreasinginteroperabilityandpotentialforautomation.

Contributing To The Deployment LifecycleAutomaticallygeneratinganAPI,fromamachinereadabledefinition,haslongbeenthedreamofAPIproviders.Inreality,thisismuchhardertoachieve,thanonemightthink,buttherehasbeensignificantworkfromleadingAPIdesignserviceprovidersandtheirdevelopercommunities,andin2014,youcanindeedautogenerateanAPIfromyourAPIdefinition.

APIdefinitionslikeAPIBlueprint,RAML,orSwagger,dowhattheydobestdescribeyourinterface.HowthismergeswiththeactualdeploymentofanAPIbackend,isnotalwaysevident.DependingonhowyoucraftyourAPIdefinition,itmaycontainyourunderlyingdatamodel,andforsimplerdataorcontentAPIs,autogenerationofabackendmightbepossible.

WhenitcomestomorecomplexAPIresources,therewillundoubtedlybemuchmoremagicbehindtheinterface,requiringconnectionwithuniquebackendsystems,andcodelibraries.ImconfidentthattheAPIcommunitywillcontinuetoproduceAPIdefinitiondriven,connectorsforcommonITsystems,furtherevolvingonthevisionofautomaticallygeneratingofAPIsfromtheirmachinereadableAPIdefinitionsreplacingmuchofwhatmoretraditionalservicegatewayshavealwaysdelivered.

Thereisalsoanewevolutionincloudcomputing,onethatwillcontributesignificantlytoAPIdeployment,beingcalledcontainers.Newapproachestodeployingapplicationresources,fromDocker,andsubsequentlyAmazon,RedHat,Google,Microsoft,andothers,willrapidlyescalatehowwedeploytheAPIsthatwedependon.APIdefinitionsprovideaperfectinterfacedefinition,forresourcesthataredeployedascontainers.Wearejustmissingthelinkingbetweencurrentcontainerdeploymentdefinitions,andtheevolvingworldofAPIdefinitionsalinkthatwillcomeintofocusin2014.

Contributing To The Management LifecycleTheearlymotivationforgenerationmachinereadabledefinitionusingSwagger,wasthepromiseofbeingabletokeepyourAPIdocumentationuptodate,whilealsoprovidinguserswithaninteractivewaytoexploreandlearnaboutyourAPI.QuicklyAPIprovidersalsodevelopedtoolingforgeneratingofclientsideAPIlibrariesinallthepopularprogramminglanguages,includingbutnotlimitedtoPHP,Python,Ruby,JavaScript,Node.js,Java,C#andGo.

MachinereadableAPIdefinitionscanalsobeusedtogeneratepermanentortemporarysandboxenvironmentsforAPIconsumers,allowingforenvironmentsthatdeveloperscanlearnaboutanAPI,beforetheyputtheAPItouseinarealproductionenvironment.Likedocumentation,sandboxenvironmentscanbecostlyandtimeconsumingtodeployandkeepuptodate,andAPIdefinitionscanhelpmakeitmuchmorepainlessandautomated.

AstheworldofAPIdesignexpands,Ithinkweshouldstopregularly,andtakealookatourAPImanagementworkflow,toseehowacentralAPIdefinitioncanhelpmanageorevenautomateotherareasofourAPIoperations.WhilewewillneverautomateallaspectsofAPImanagement,APIdefinitionscanprovideacentraltruththatcanbeappliedinmanyunexpectedways.

Contributing To The Testing & Monitoring LifecycleWhenitcomestotesting,andmonitoringanAPI,youbegintoreallyseehowmachinereadableAPIdefinitionscanbethetruth,inthecontractbetweenAPIproviderandconsumer.APIdefinitionsarebeingusedbyAPItestingandmonitoringserviceslikeSmartBear,providingacentralsetofrulesthatcanensureyourAPIsdeliveraspromised.

MakingsureallyourAPIsoperateasexpected,andjustlikegeneratinguptodatedocumentation,youcanensuretheentiresurfaceareaofyourAPIistested,andoperatingasintended.Testdrivendevelopment(TDD)isbecomingcommonpracticeforAPIdevelopment,andAPIdefinitionswillplayanincreasingroleinthissideofAPIoperations.

AnAPIdefinitionprovidesacentraltruth,thatcanbeusedbyAPIproviderstomonitorAPIoperations,butalsogivethesamesetofrulestoexternalAPImonitoringservices,aswellasindividualAPIconsumers.Monitoring,andunderstandinganAPIuptime,frommultipleexternalsourcesisbecomingapartofhowtheAPIeconomyisstabilizingitself,andAPIdefinitionsprovideaportabletemplate,thatcanbeusedacrossallAPImonitoringservices.

Testingandmonitoringofvitalresourcesthatapplicationsdependonisbecomingthenorm,withnewserviceprovidersemergingtoassistinthisarea,andlargetechnologycompanieslikeGoogle,makingtestingandmonitoringdefaultinallplatformoperations.WithoutasetofinstructionsthatdescribetheAPIsurfacearea,itwillbecumbersome,andcostly,togeneratetheautomatedtestingandmonitoringjobsnecessarytoproduceastable,APIeconomy.

Contributing To The Discovery LifecycleOneofthenewestincentivesforAPIproviderstodevelopmachinereadableAPIdefinitions,isaboutAPIdiscovery.AftermanyyearsofnosearchsolutionforAPIs,beyondthestandardAPIdirectory,wearejustnowbeginningtoseeanewgenerationofAPIdiscoverytoolingandservices.

Togetherwith3Scale,IrecentlylaunchedtheAPIs.jsondiscoveryformat,lookingtocreateasingleAPIdiscoveryframeworkthatcanlivewithintherootofanydomain.OurgoalistoallowAPIproviderstodescribetheirAPIs,providingmachinereadablepointerstothecommonbuildingblocksofacompany'sAPIlikesignup,machinereadabledefinitions,documentation,termsofservice,andmuch,muchmore.

AsweweredevelopingAPIs.json,werecognizedthatwithoutaproper,distributedsearchengine,anymachinereadableAPIdiscoveryformatswouldnotbesuccessful,andwiththisinmind3ScalelaunchedanopensourceAPIsearchengine,withthefirstimplementationbeingAPIs.io.AsthenumberofAPIsrapidlygrows,moresearchsolutionslikeAPIs.iowillbeneededtomakesurethemostvaluableAPIsarediscoverable,inrealtime.

ThefutureofAPIdiscoverywillneedmorethanjustbasicmetadatatofindAPIs,wewillneedmachinereadabledefinitionsthatdescribetheAPI,aswellasitssupportingbuildingblocks.APIdefinitionswillhelpautomatethediscoveryandunderstandingofwhatvalueanAPIdelivers,helpingAPIconsumersfindjusttheAPIresourcestheyneedtomaketheirapplicationssuccessful.

An Evolutionary Period For API DesignGoodAPIdesignpractices,toolsandserviceshaveamajorimpactdownstreamwithinAPIinitiatives.AsmorecompaniesreachamaturitypointwiththeirAPIefforts,thedesiretorefineAPIdesignbeforeincurringthecostsassociatedwithdeploymentandmanagement,whileworkingtomitigaterisks,willonlyincrease.

APIdesignhasbeenhistoricallyhitchedtoRESTfuldogmaandearlySOApractictionersvisionofAPIdiscovery.AsthewebAPIworldmatures,APIdesignisalsobecomingaboutdeployment,documentation,codesamples,testing,monitoring,anddiscovery,andotheressentialbuildingblocksofahealthyAPIlifecycle.

APIdesignshouldbefirstandforemostaboutdeliveringquality,consistentandmeaningfulAPIendpoints,whilealsodeliveringvalueformanagement,discoveryandintegration.Incomingyears,wewillseespecificindustriesrealizetheirroleinleadingAPIdesignenergy,healthcare,transportation,environment,andotherindustrieswillhelpdefinemeaningfulAPIdesignstandardsfortheirindustriesthroughpartnerships,governmentleadership,andmostimportantly,successfulpatternsestablishedbyexistingAPIleaders.

MyresearchprojectintoAPIdesignismeanttoidentifytheevolvingbuildingblocks,toolsandcompaniesthatarecontributingtothesuccessoftheAPIdesignsector.Moreresourcesareprovidedbelowasanappendix,butyoucanalsofindeverythingpublishedtoGithubatdesign.apievangelist.com,whilealsobeingpublishedasthiswhitepapertoprovidethelargestpossiblereachforthisvaluableinformation.

TheAPIindustryhascomeofage,andthingsarerapidlyevolvingwhenitcomestodefiningbestpracticesandprovidingtoolsthatwillassistcompaniesanddevelopersachievethebestpossibleAPIdesignputtingusinaveryimportantperiodfortheAPIeconomy.

www.apievangelist.cominfo@apievangelist.com

Appendix A: Curated News and ResourcesAPIFirstDevelopmentwithRAMLandSoapUI[Webinar]fromfeedproxy.google.comon6/19/2014),fullresourceavailableathttp://feedproxy.google.com/~r/muleblog/~3/SYHjihCKVqI/IntroducingTheRESTedNARWHLAPracticalAPIDesignFrameworkfromfeedproxy.google.comon6/17/2014),fullresourceavailableathttp://feedproxy.google.com/~r/MasheryBlog/~3/b3GnPhQIvk/introducingrestednarwhlpracticalapidesignframeworkHappinessisawelldesignedAPI|ZDNetfromwww.zdnet.comon6/6/2014),fullresourceavailableathttp://www.zdnet.com/happinessisawelldesignedapi7000030282/SwaggerLevelsTheAPIDesignPlayingFieldWithNewEditorAndYAMLDefinitionsfromapievangelist.comon6/5/2014),fullresourceavailableathttp://apievangelist.com/2014/06/05/swaggerlevelstheapidesignplayingfieldwithneweditorandyamldefinitions/APIdocumentationmadebeautifulwithApiary.io|ITworldfromwww.itworld.comon2/28/2014),fullresourceavailableathttp://www.itworld.com/development/407333/apidocumentationmadebeautifulapiaryioAPracticalbyD.KeithCaseyJretal.[PDF/iPad/Kindle]fromleanpub.comon2/27/2014),fullresourceavailableathttps://leanpub.com/restfulapidesignApplicationProgrammingeXperience:Itsallabout*XMobileAppsStufffrommanfredbo.tumblr.comon1/28/2014),fullresourceavailableathttp://manfredbo.tumblr.com/post/74280033341/applicationprogrammingexperienceitsallaboutxJakubNesetril,CEOofApiaryonWebAPIsandDeveloperExperiencefromwww.infoq.comon1/28/2014),fullresourceavailableathttp://www.infoq.com/interviews/jakubapisdxTheHumanAspectsofAPIDesign:AnInterviewwithApiary'sJakubNesetrilfromwww.infoq.comon11/14/2013),fullresourceavailableathttp://www.infoq.com/news/2013/11/apiaryjakubnesetrilinterviewMoreThoughtsonanAPICommonsfromwww.3scale.neton11/10/2013),fullresourceavailableathttp://www.3scale.net/2013/11/towardsapicommonsfortheapieconomy/DesigningAPIsfortheInternetofThings(IoT)fromwww.layer7tech.comon10/30/2013),fullresourceavailableathttp://www.layer7tech.com/blogs/index.php/designingapisfortheinternetofthingsiot/APIsAtTheHeartofyourMobileAppStrategyfromblog.soa.comon10/28/2013),fullresourceavailableathttp://blog.soa.com/apisattheheartofyourmobileappstrategy/NomoreoutdatedAPIdocumentation!fromblog.apiary.ioon10/10/2013),fullresourceavailableathttp://blog.apiary.io/2013/10/10/NomoreoutdatedAPIdocumentation/RAMLRESTfulAPImodelinglanguagefromraml.orgon10/2/2013),fullresourceavailableathttp://raml.org/index.htmlNewAPIBlueprintavailableatApiaryfromblog.apiary.ioon10/2/2013),fullresourceavailableathttp://blog.apiary.io/2013/10/02/NewAPIBlueprintavailable/ApiaryIsGrowingfromblog.apiary.ioon9/17/2013),fullresourceavailableathttp://blog.apiary.io/2013/09/17/ApiaryIsGrowing/JSONandXMLfromdeveloper.infoconnect.comon9/3/2013),fullresourceavailableathttp://developer.infoconnect.com/jsonandxmlMASHERYI/ODOCSDOCSTHATROCKfromwww.mashery.comon8/27/2013),fullresourceavailableathttp://www.mashery.com/blog/masheryiodocsdocsrockDesigningAPIsforAsynchronyfromblog.izs.meon8/24/2013),fullresourceavailableathttp://blog.izs.me/post/59142742143/designingapisforasynchronyPluralsightWebAPIDesignwithShawnWildermuthEBooks+Tutorials...fromskdown.neton8/21/2013),fullresourceavailableathttp://skdown.net/forum/index.php/showtopic=4317200ApiDesign,Part1:RestIsTheLeadingButNotOnly...fromwww.forrester.comon8/20/2013),fullresourceavailableathttp://www.forrester.com/API+Design+Part+1+REST+Is+The+Leading+But+Not+Only+Option+For+Your+APIs/fulltext//ERES102021ApiDesign,Part2:DesignMessagingStylesByBalancing...fromwww.forrester.comon8/20/2013),fullresourceavailableathttp://www.forrester.com/API+Design+Part+2+Design+Messaging+Styles+By+Balancing+Reach+With+Your+Other+Design+Goals/fulltext//ERES102022ApiDesign,Part3:MakeTransactionsAndErrorHandling...fromwww.forrester.comon

8/20/2013),fullresourceavailableathttp://www.forrester.com/API+Design+Part+3+Make+Transactions+And+Error+Handling+Clear+In+Your+API+Designs/fulltext//ERES102023ApiDesign,Part4:FutureproofAndSecureYourApis...fromwww.forrester.comon8/20/2013),fullresourceavailableathttp://www.forrester.com/API+Design+Part+4+FutureProof+And+Secure+Your+APIs+To+Fit+Your+Usage+Scenarios/fulltext//ERES102024TheSecretsofAwesomeJavaScriptAPIDesignfromcss.dzone.comon8/16/2013),fullresourceavailableathttp://css.dzone.com/articles/secretsawesomejavascriptapiTheImportanceofImpermanenceinAPIDesignfromwww.programmableweb.comon8/6/2013),fullresourceavailableathttp://www.programmableweb.com/2013/08/06/theimportanceofimpermanenceinapidesignJoshuaBloch:BumperStickerAPIDesignfromwww.infoq.comon7/27/2013),fullresourceavailableathttp://www.infoq.com/articles/APIDesignJoshuaBlochMicroServiceArchitecturefromyobriefca.seon7/9/2013),fullresourceavailableathttp://yobriefca.se/blog/2013/04/29/microservicearchitecture/ADL'sExperienceAPIDesignWorkingGroupKickOffonJuly15fromelearningindustry.comon7/9/2013),fullresourceavailableathttp://elearningindustry.com/adlsexperienceapidesignworkinggroupkickoffonjuly15APIDesign:ANewModelforPragmaticRESTfromblog.apigee.comon7/4/2013),fullresourceavailableathttps://blog.apigee.com/detail/api_design_a_new_model_for_pragmatic_restAPIDesign:HarnessingHATEOAS,Part2fromblog.apigee.comon7/3/2013),fullresourceavailableathttps://blog.apigee.com/detail/api_design_harnessing_hateoas_part_2Signsyou'reveeringfromgoodAPIdesignfromblog.apiaxle.comon7/3/2013),fullresourceavailableathttp://blog.apiaxle.com/post/signsyoureveeringfromgoodapidesign/APICraftingSecrets:IntoFlightstatsAPIsfromwww.3scale.neton7/2/2013),fullresourceavailableathttp://www.3scale.net/2013/07/apicraftingsecretsintoflightstatsapis/PracticalAPIDesign:ConfessionsofaJavaFrameworkArchitectfromwww.tinydl.comon6/29/2013),fullresourceavailableathttp://www.tinydl.com/1060908845practicalapidesignconfessionsofajavaframeworkarchitect.htmlBetterRestAPIdesign1fromhaodeng.blogspot.comon6/27/2013),fullresourceavailableathttp://haodeng.blogspot.com/2013/06/betterrestapidesign1.htmlAPIDesign:HarnessingHATEOAS,Part1fromblog.apigee.comon6/20/2013),fullresourceavailableathttps://blog.apigee.com/detail/api_design_harnessing_hateoas_part_1WhenGoodAPIDesignisaWasteofTimefromwww.layer7tech.comon6/19/2013),fullresourceavailableathttp://www.layer7tech.com/blogs/index.php/whengoodapidesignisawasteoftime/APIDesign:HoninginonHATEOASfromblog.apigee.comon6/17/2013),fullresourceavailableathttps://blog.apigee.com/detail/api_design_honing_in_on_hateoasRESTfulAPIs:WhiteHouseSetsTheStandard(s)fromwww.programmableweb.comon6/17/2013),fullresourceavailableathttp://www.programmableweb.com/2013/06/17/restfulapiswhitehousesetsthestandards/AHypermediaAPIReadingListLiterateProgrammingfromblog.steveklabnik.comon6/12/2013),fullresourceavailableathttp://blog.steveklabnik.com/posts/20120227hypermediaapireadinglistAtlassianRESTAPIDesignGuidelinesversion1Documentationfromdeveloper.atlassian.comon6/12/2013),fullresourceavailableathttps://developer.atlassian.com/display/DOCS/Atlassian+REST+API+Design+Guidelines+version+1DesigningHypermediaAPIsfromwww.designinghypermediaapis.comon6/11/2013),fullresourceavailableathttp://www.designinghypermediaapis.com/APIDesignWikifromwiki.apidesign.orgon6/11/2013),fullresourceavailableathttp://wiki.apidesign.org/wiki/Main_PageWebAPIDesignCookbookfromwww.w3.orgon6/11/2013),fullresourceavailableathttp://www.w3.org/TR/apidesign/SwaggerwithWSO2APIManagerfromblog.cobia.neton5/31/2013),fullresourceavailableathttp://blog.cobia.net/cobiacomm/2013/05/31/swaggerwithwso2apimanager/APIHierarchyofNeeds|APIUXfromapiux.comon5/30/2013),fullresourceavailableathttp://apiux.com/2013/05/29/apihierarchyneeds/StopDesigningFragileWebAPIsbyMathieuFenniakfrommathieu.fenniak.neton4/29/2013),full

resourceavailableathttps://mathieu.fenniak.net/stopdesigningfragilewebapis/WhiteHouseAPIStandardsfromgithub.comon4/26/2013),fullresourceavailableathttps://github.com/WhiteHouse/apistandardsThreeWaystoThinkAboutAPIDesignfromwww.programmableweb.comon4/26/2013),fullresourceavailableathttp://www.programmableweb.com/2012/02/14/threewaystothinkaboutapidesign/RESTAPIDesignRulebookfromshop.oreilly.comon4/26/2013),fullresourceavailableathttp://shop.oreilly.com/product/0636920021575.doAPIDesignandArchitectureBootCampfromLayer7fromwww.layer7tech.comon4/26/2013),fullresourceavailableathttp://www.layer7tech.com/services/apidesignandarchitecturebootcampAPIDesignandDocumentationfromwww.howto.govon4/26/2013),fullresourceavailableathttp://www.howto.gov/digitalgovsplash.php/redirect_to=category/code/api/APIDesignfromApigeefromapigee.comon4/26/2013),fullresourceavailableathttp://apigee.com/about/apibestpractices/apidesign/allHowtoDesignaGoodAPI&WhyitMattersfromwww.infoq.comon4/26/2013),fullresourceavailableathttp://www.infoq.com/presentations/effectiveapidesignDesigningAPIsforHumansfromjohnsheehan.comon4/25/2013),fullresourceavailableathttp://johnsheehan.com/blog/designingapisforhumansAPIsasArtfromapievangelist.comon3/19/2013),fullresourceavailableathttp://apievangelist.com/2013/03/19/apisasart/APIDesign&DevelopmentGuidelinesfromwww.dzone.comon2/16/2013),fullresourceavailableathttp://www.dzone.com/links/r/api_design_amp_development_guidelines_selected_re.htmlAPIDesignfromApigee3rdEditionfromblog.apigee.comon1/16/2013),fullresourceavailableathttps://blog.apigee.com/detail/api_design_third_edition_video_slidesODataandImpactonAPIDesign(video&slides)fromblog.apigee.comon6/3/2012),fullresourceavailableathttps://blog.apigee.com/detail/odata_and_impact_on_api_design_video_slides/APIDesignbyMattGemmellfrommattgemmell.comon5/24/2012),fullresourceavailableathttp://mattgemmell.com/apidesign/