names503

SDMXSTANDARDS:SECTION7GUIDELINESFORTHEUSEOFWEBSERVICESVERSION2.
1(UPDATEAPRIL2013)Thisdocumentisout-of-date;pleasenotethattheSDMXSOAPandRESTspecificationsarenowmaintainedonGitHub(https://github.
com/sdmx-twg)Thisdocumentisout-of-date;pleasenotethattheSDMXSOAPandRESTspecificationsarenowmaintainedonGitHub(https://github.
com/sdmx-twg)2Contents1Introduction.
52WebServicesandSDMX-ML53SOAP-BasedSDMXWebServices:WSDLOperationsandBehaviours.
.
.
.
73.
1Introduction.
73.
2TheSDMXWeb-ServicesNamespace73.
3SupportforWSDLOperations73.
4ListofWSDLOperations73.
4.
1Data83.
4.
2Metadata.
83.
4.
3Structureusage.
83.
4.
4Structure93.
4.
5Itemscheme93.
4.
6Othermaintainableartefacts93.
4.
7XMLSchemas(XSD)103.
4.
8Genericqueryforstructuralmetadata103.
5OtherBehaviours.
103.
5.
1VersioningDefaults.
103.
5.
2ResolvingReferencesandSpecifyingReturnedObjects.
103.
5.
3Enablingcompression.
113.
5.
4ImplementationoftheSOAPbasedSDMXWebServices113.
5.
5CompliancewithWS-I.
114SDMXRESTfulAPI114.
1ABriefIntroductiontoREST.
114.
2ScopeoftheAPI.
124.
3StructuralMetadataQueries.
1234.
3.
1Resources.
124.
3.
2Parameters134.
3.
3Examples174.
4DataandMetadataQueries.
194.
4.
1Resources.
194.
4.
2Parameters194.
4.
3Examples244.
5Schemaqueries.
244.
5.
1Resources.
244.
5.
2Parameters254.
5.
3Examples264.
6SelectionoftheAppropriateRepresentation.
264.
7Enablingdatacompression.
275StandardErrorsforSDMXWebServices.
275.
1Introduction.
275.
2ErrorhandlinginRESTWebService.
285.
3SOAPWebService285.
4Errorcategories.
285.
5Client-CausedErrors285.
5.
1Noresultsfound–100285.
5.
2Unauthorized–110.
295.
5.
3ResponseTooLargeDuetoClientRequest130295.
5.
4Syntaxerror–140.
295.
5.
5Semanticerror–150.
295.
6Server-CausedErrors.
295.
6.
1InternalServerError–500.
295.
6.
2Notimplemented–5012945.
6.
3Serviceunavailable–503295.
6.
4Responsesizeexceedsservicelimit-510.
295.
7CustomErrors–1000+305.
8SDMXtoHTTPErrorMapping306Annex:Examples.
316.
1SampleQueriesforaWebServicesClient316.
1.
1Step1:BrowsinganSDMXdatasource,usingalistofsubject-matterdomains316.
1.
2STEP2:Selectingadataflow.
326.
1.
3STEP3:Dataselection356.
2SampleErrorElementinanSDMXmessage376.
3SoapFaultexample.
387Annex:Securityguidelines.
397.
1Authentication.
397.
1.
1Serverauthentication397.
1.
2Clientauthentication.
397.
2Confidentiality.
397.
3Integrity.
39SDMX2012http://www.
sdmx.
org/51Introduction1WebservicesrepresentthecurrentgenerationofInternettechnologies.
Theyallowcomputer2applicationstoexchangedatadirectlyovertheInternet,essentiallyallowingmodularor3distributedcomputinginamoreflexiblefashionthaneverbefore.
Inordertoallowweb4servicestofunction,however,manystandardsarerequired:forrequestingandsupplying5data;forexpressingtheenvelopingdatawhichisusedtopackageexchangeddata;for6describingwebservicestooneanother,toallowforeasyintegrationintoapplicationsthatuse7otherwebservicesasdataresources.
8SDMX,withitsfocusontheexchangeofdatausingInternettechnologiesprovidessomeof9thesestandardsrelatingtostatisticaldataandmetadata.
Manyweb-servicesstandards10alreadyexist,however,andthereisnoneedtore-inventthemforusespecificallywithinthe11statisticalcommunity.
Specifically,SOAP(whichoriginallystoodforthe"SimpleObject12AccessProtocol")andtheWebServicesDescriptionLanguage(WSDL)canbeusedby13SDMXtocomplementthedataandmetadataexchangeformatstheyarestandardizing.
Inthe14webservicesworld,theREST("RepresentationalStateTransfer")protocolisalsooftenused,15relyingonaURL-basedsyntaxtoinvokewebservices.
SuchREST-basedservicescanbe16describedinastandardfashionusingWADL("WebApplicationDescriptionLanguage"),in17thesamewaythatXML-invokedwebservicesbasedonSOAPcanbedescribedusing18WSDL.
19DespitethepromiseofSOAPandWSDL,itbecameevidentfromearlyimplementationsby20vendorsthatthesewerenot,infact,interoperable.
ItwasforthisreasonthattheWeb21Services-Interoperability(WS-I)initiativewasstarted.
Thisconsistsofagroupofvendors22whohaveallimplementedthesameweb-servicesstandardsthesameway,andhaveverified23thisfactbydoinginteroperabilitytests.
Theypublishprofilesdescribinghowtouseweb24servicesstandardsinteroperably.
SDMXusestheworkofWS-Iasappropriatetomeetthe25needsofthestatisticalcommunity.
26ThisdocumentprovidesseveralSDMX-specificguidelinesforusingtheexistingstandardsin27afashionwhichwillpromoteinteroperabilityamongSDMXwebservices,andallowforthe28creationofgenericclientapplicationswhichwillbeabletocommunicatemeaningfullywith29anySDMXwebservicewhichimplementstheseguidelines.
30Muchofthecontentofthisdocumentisnotnormative–insteadtheintentionistosuggesta31bestpracticeinusingSDMX-MLdocumentsandwebservicesstandardsfortheexchangeof32statisticaldataandmetadata.
However,theSDMXWSDLandWADLfilesthatformalise,in33XML,theAPIsdescribedinthisdocumentarenormative.
342WebServicesandSDMX-ML35Conventionalapplicationsandservicestraditionallyexposetheirfunctionalitythrough36applicationprogramminginterfaces(APIs).
Webservicesarenodifferent–theyprovidea37publicversionofthefunctioncallswhichcanbeaccessedoverthewebusingweb-services38protocols(SOAPorREST).
Inordertomakeasetofwebservicesinteroperate,itis39necessarytohaveastandardabstraction,ormodel,onwhichthesepublicfunctionsare40based.
SDMXbenefitsfromhavingacommoninformationmodel,anditisanatural41extensiontousetheSDMXInformationModelasthebasisforstandardweb-servicesfunction42calls.
43WebservicesexchangedatainanXMLformat:thisishowthedatapassedbetweenweb44servicesisformatted.
SDMX-ML,asastandardXMLforexchangingdataandstructural45metadatawithinthestatisticalrealm,providesausefulXMLformatforthepublicserialization46ofweb-servicesdata.
Whiletherearesometechniquesforsimpleweb-servicesdata476exchanges–remoteprocedurecalls(RPCs)–whichareoftenused,theuseofasetofXML48exchangesbasedonacommoninformationmodelisseenasabetterapproachforachieving49interoperability.
50ThereareseveraldifferentdocumenttypesavailablewithinSDMX-ML,andallare51potentiallyimportanttothecreatorsandusersofSDMXwebservices.
52531.
The"Structure"Message:Thismessagedescribestheconcepts,dataand54metadatastructuredefinitions,andcodelistswhichdefinethestructureof55statisticaldataandreferencemetadata.
EverySDMX-compliantdatasetor56metadatasetmusthaveadataormetadatastructuredefinitiondescribedforit.
57ThisXMLdescriptionmustbeavailablefromanSDMXwebservicewhenitis58askedfor.
592.
The"Generic"DataMessage:Thisisthe"generic"wayofmarkingupanSDMX60dataset.
Thisschemadescribesanon-data-structure-definition-specificformat61forexchangingSDMXdata,anditisarequirementthateverySDMXdataweb62servicemakesitsdataavailableinatleastthisform.
Itisexpectedthat,inmany63instances,otherdata-structure-definition-specificXMLformsforexpressingdata64willalsobesupportedinparallelservices.
653.
The"StructureSpecific"DataMessage:Thisisastandardschemaformat66derivedfromthestructuredescriptionusingastandardizedmapping,andmany67standardtags.
Itisspecifictothestructureofaparticulardatastructuredefinition,68andsoeverydatastructuredefinitionwillhaveitsown"structurespecific"69schemas.
Itisdesignedtoenabletheexchangeoflargedatasets,Thisisadata70formatthatawebservicemaywishtoprovide,dependingontherequirementsof71thedatatheyexchange.
724.
The"Query"Messages:ThisisthesetofmessagesusedtoinvokeSOAP-73basedSDMXwebservices.
Thesemessagesallconforminaconsistentwaytoa74mastertemplate,butaredecomposedintospecificqueriestoalloweachservice75tosupportonlythosefieldsinthetemplatemessagewhicharemeaningfultoit.
76Thesequerymessagesaregenericacrossalldataandmetadatastructure77definitions,makingqueriesintermsofthevaluesspecifiedfortheconceptsofa78specificstructure(asspecifiedinastructuredescription).
Itallowsuserstoquery79fordata,concepts,codelists,dataandmetadatastructuredefinitions.
805.
The"RegistryInterfaces"Message:AlloftheRegistryInterfacesaresub-81elementsofthisSDMX-MLMessagetype.
Theyaremorefullydescribedinthe82SDMXRegistrySpecification.
836.
The"Generic"MetadataMessage:Thisisamessageusedtoreportreference84metadataconcepts,whichisgenericacrossalltypesofreferencemetadata85structuraldescriptions.
867.
The"StructureSpecific"MetadataMessage:Thisisamessageusedtoreport87referencemetadataconceptsspecifictoaparticularmetadatastructuredefinition.
8873SOAP-BasedSDMXWebServices:WSDL89OperationsandBehaviours903.
1Introduction91ThissectionaddressestheoperationsandbehavioursspecifictoSOAP-basedWebServices.
92MostimportantisalistofstandardWSDLoperations,whichwillformthebasisof,andbe93accompaniedby,actualstandardWSDLXMLinstances,foruseindevelopmentpackages.
94Therearealsoseveralguidelinesfortheimplementationofwebservices,tosupport95interoperability.
96AllSDMXSOAPwebservicesshouldbedescribedusingWSDLinstances.
Theglobal97elementforeachXMLdataandmetadataformatwithinSDMXshouldbespecifiedasthe98contentoftherepliestoeachexchange.
Thefunctionnamesforeachidentifiedpatternare99specifiedbelow,alongwiththetypeofSDMX-MLpayload.
100BecauseSOAPRPCisnotsupported,the"parameters"ofeachfunctionaresimplyan101instanceoftheappropriateSDMX-MLmessagetype.
Asnotedabove,should102beusedtospecifytheschemaforamultiple-messageexchange.
ThedistributedWSDLfiles103illustratehowSOAPmessagesshouldbeused.
104ThebindingsincludedinthedistributedWSDLfilesareaccordingtoSOAP1.
1.
1053.
2TheSDMXWeb-ServicesNamespace106TheSDMXWebServicesnamespace1containsasetofmessagesspecifictotheuseof107SOAP-basedservices.
Eachoftheoperationsdescribedwillhaveamessagetoinvokethe108Web-Service,andaresponsemessage.
Ineachcase,thesearerefinementsofotherSDMX109messages,appropriatetotheoperationbeingperformed–thesearedescribedinthelistof110operations,below.
111Additionally,thereisalistoferrorcodestobeusedintheSOAPenvelope(seethestandard112errorcodessection).
1133.
3SupportforWSDLOperations114AnSDMXwebservicemustsupportallofthelistedoperations,evenifthesupportisminimal,115andonlyinvolvesthegenerationofanerrorexplainingthattherequestedoperationhasnot116beenimplemented.
Thisisnecessaryforthesakeofinteroperability.
1173.
4ListofWSDLOperations118FortheuseofSOAPandWSDL,theWebServicesInteroperabilityspecificationversion1.
1119shouldbefollowed.
1201i.
e.
,thedeclarednamespaceoftheSDMXWSDLdefinition.
83.
4.
1Data1213.
4.
1.
1GetStructureSpecificData122ThisoperationisinvokedusingaGetStructureSpecificDataRequestmessage,andreceivesa123GetStructureSpecificDataResponseasareply.
1243.
4.
1.
2GetGenericData125ThisoperationisinvokedusingaGetGenericDataRequestmessage,andreceivesa126GetGenericDataResponseasareply.
1273.
4.
1.
3GetStructureSpecificTimeSeriesData128ThisoperationisinvokedusingaGetStructureSpecificTimeSeriesDataRequestmessage,and129receivesaGetStructureSpecificTimeSeriesDataResponseasareply.
1303.
4.
1.
4GetGenericTimeSeriesData131ThisoperationisinvokedusingaGetGenericTimeSeriesDataRequestmessage,andreceives132aGetGenericTimeSeriesDataResponseasareply.
1333.
4.
2Metadata1343.
4.
2.
1GetGenericMetadata135ThisoperationisinvokedusingaGetGenericMetadataRequestmessage,andreceivesa136GetGenericMetdataResponseasareply.
1373.
4.
2.
2GetStructureSpecificMetadata138ThisoperationisinvokedusingaGetStructureSpecificRequestmessage,andreceivesa139GetStructureSpecificResponseasareply.
1403.
4.
3Structureusage1413.
4.
3.
1GetDataflow142ThisoperationisinvokedusingaGetDataflowRequestmessage,andreceivesa143GetDataflowResponseasareply.
1443.
4.
3.
2GetMetadataflow145ThisoperationisinvokedusingaGetMetadataflowRequestmessage,andreceivesa146GetMetadataflowResponseasareply.
14793.
4.
4Structure1483.
4.
4.
1GetDataStructure149ThisoperationisinvokedusingaGetDataStructureRequestmessage,andreceivesa150GetDataStructureResponseasareply.
1513.
4.
4.
2GetMetadataStructure152ThisoperationisinvokedusingaGetMetadataStructureRequestmessage,andreceivesa153GetMetadataStructureResponseasareply.
1543.
4.
5Itemscheme1553.
4.
5.
1GetCategoryScheme156ThisoperationisinvokedusingaGetCategorySchemeRequestmessage,andreceivesa157GetCategorySchemeResponseasareply.
1583.
4.
5.
2GetConceptScheme159ThisoperationisinvokedusingaGetConceptSchemeRequestmessage,andreceivesa160GetConceptSchemeResponseasareply.
1613.
4.
5.
3GetCodelist162ThisoperationisinvokedusingaGetCodelistRequestmessage,andreceivesa163GetCodelistResponseasareply.
1643.
4.
5.
4GetHierarchicalCodelist165ThisoperationisinvokedusingaGetHierarchicalCodelistRequestmessage,andreceivesa166GetHierarchicalCodelistResponseasareply.
1673.
4.
5.
5GetOrganisationScheme168ThisoperationisinvokedusingaGetOrganisationsSchemeRequestmessage,andreceivesa169GetOrganisationSchemeResponseasareply.
1703.
4.
5.
6GetReportingTaxonomy171ThisoperationisinvokedusingaGetReportingTaxonomyRequestmessage,andreceivesa172GetReportingTaxonomyResponseasareply.
1733.
4.
6Othermaintainableartefacts1743.
4.
6.
1GetStructureSet175ThisoperationisinvokedusingaGetStructureSetRequestmessage,andreceivesa176GetStructureSetResponseasareply.
177103.
4.
6.
2GetProcess178ThisoperationisinvokedusingaGetProcessRequestmessage,andreceivesa179GetProcessResponseasareply.
1803.
4.
6.
3GetCategorisation181ThisoperationisinvokedusingaGetCategorisationRequestmessage,andreceivesa182GetCategorisationResponseasareply.
1833.
4.
6.
4GetProvisionAgreement184ThisoperationisinvokedusingaGetProvisionAgreementRequestmessage,andreceivesa185GetProvisionAgreementResponseasareply.
1863.
4.
6.
5GetConstraint187ThisoperationisinvokedusingaGetConstraintRequestmessage,andreceivesa188GetConstraintResponseasareply.
1893.
4.
7XMLSchemas(XSD)1903.
4.
7.
1GetDataSchema191ThisoperationisinvokedusingaGetDataSchemaRequestmessage,andreceivesa192GetDataSchemaResponseasareply.
1933.
4.
7.
2GetMetadataSchema194ThisoperationisinvokedusingaGetMetadataSchemaRequestmessage,and195receivesaGetMetadataSchemaResponseasareply.
1963.
4.
8Genericqueryforstructuralmetadata1973.
4.
8.
1GetStructures198ThisoperationisinvokedusingaGetStructuresRequestmessage,andreceivesa199GetStructuresResponseasareply.
2002013.
5OtherBehaviours2023.
5.
1VersioningDefaults203Whennoversionisspecifiedinthemessageinvokingaservice,thedefaultistoreturnthe204lastproductionversionoftheresource(s)requested.
2053.
5.
2ResolvingReferencesandSpecifyingReturnedObjects206Version2.
1oftheSDMX-MLQuerymessageoffersnewfunctionalitytoresolvereference207andspecifythetypeofobjectstobereturned.
TheSOAPAPIreliesonthismechanismfor20811resolvingreferencesandspecifyingreturnedobjects.
SeeSection"Applicabilityandmeaning209ofreferencesattribute".
2103.
5.
3Enablingcompression211CompressionshouldbeenabledusingtheappropriateHTTPHeaderfield(Accept-Encoding).
2123.
5.
4ImplementationoftheSOAPbasedSDMXWebServices213IntheSDMXWebServices,thedevelopmentisContract-FirstsincetheWSDLhasbeen214specifiedbythestandard.
FurthermoreitisaWebServiceofalreadypreparedXML215messagesrequests/responses,i.
e.
theinterfacesfortheapplicationlogicaretheXML216messages.
Thereforethereisnoneedtogeneratestubsforserialisationandde-serialisation217oftheSOAPpayloadsfrom/tothenativelanguageclasses.
Theindicativewayistohavefull218controlontheXMLmessagesrequests/responses.
Whenusingtheautomaticgenerationof219codeitwillincludeanextraelementfortheparameteroftheoperationintheSOAPrequest220accordingtotheRPCparadigm,andtotheSOAPspecificationsthatisnotdesiredaccording221tothestandardisedSDMXWSDL.
222WhenusingApacheAxisinJava,aninterfacefortheserviceisofferedbythetoolkitthat223reads/returnstheXMLpayloadsusingDOMelements(DOMElementinAxis2).
Moreover224whenusingtheJavaAPIforXMLWebServices(JAX-WS),thedevelopercanuse225theProviderinterface,whereheisresponsibleforcreatingtheSOAP226requestandresponsemessagesaswellasspecifyingthestandardisedWSDLoftheservice.
227Howeverinthe.
NETenvironmentthereisnosimilarsolutionforthis.
Thedeveloperofthe228servicewillhavetousetheXmlAnyElementparameterforthe.
NETwebmethods.
This229specifiesthattheparameteroftheServicemethodcanbeanyXMLelementthusallowsthe230developertotakecontroloftheXMLpayload.
Thedetailsofthisapproacharepresentedin231the"AnnexI:Howtoeliminateextraelementinthe.
NETSDMXWebService"inthesection23206oftheSDMXdocumentation.
2333.
5.
5CompliancewithWS-I234ToensureinteroperabilitybetweenSDMXwebservices,compliancewithsectionsoftheWS-I235Profile1.
1isrecommendedforallSDMXwebservices.
Thedocumentationcanbefound236athttp://www.
ws-i.
org/Profiles/BasicProfile-1.
1-2004-08-24.
html.
Therecommendedsections237arethoseconcerningtheuseofSOAPandWSDL.
UDDI,whileusefulforadvertisingthe238existenceofSDMXwebservices,isnotnecessarilycentraltoSDMXinteroperability.
2394SDMXRESTfulAPI2404.
1ABriefIntroductiontoREST241ThisSDMXAPIisbasedontheRESTprinciples,asdescribedbelow:242InREST,specificinformationisknownas"Resource".
InSDMX,specificresources243wouldbe,forexample,codelists,conceptschemes,datastructuredefinitions,244dataflows,etc.
Eachresourceisaddressableviaaglobalidentifier(i.
e.
:aURI).
245ManipulatingresourcesisdoneusingmethodsdefinedintheHTTPprotocol(e.
g.
:246GET,POST,PUT,DELETE).
ThisAPIfocusesondataretrieval,and,therefore,only247theusageofHTTPGETiscoveredinthisdocument.
24812Aresourcecanberepresentedinvariousformats(suchasthedifferentflavoursand249versionsoftheSDMX-MLstandard).
Selectionoftheappropriaterepresentationis250doneusingHTTPContentNegotiationandtheHTTPAcceptrequestheader.
2514.
2ScopeoftheAPI252TheRESTfulAPIfocusesonsimplicity.
Theaimisnottoreplicatethefullsemanticrichness253oftheSDMX-MLQuerymessagebuttomakeitsimpletoperformalimitedsetofstandard254queries.
Also,incontrasttootherpartsoftheSDMXspecification,theRESTfulAPIfocuses255solelyondataretrieval(viaHTTPGET).
Morespecifically,theAPIallows:256Toretrievestructuralmetadata,usingacombinationofid,agencyIDandversion257number.
258Toretrievestatisticaldataorreferencemetadatausingkeys(withoptionsfor259wildcardingandsupportfortheORoperator),dataormetadataflowsanddataor260metadataproviders.
261Tofurtherrefinequeriesforstatisticaldataorreferencemetadatausingtime262information(startperiodandendperiod).
263Toretrieveupdatesandrevisionsonly.
264Toreturntheresultsofaqueryinvariousformats.
Thedesiredformatandversionof265thereturnedmessagewillbespecifiedusingHTTPContentNegotiation(andthe266HTTPAcceptrequestheader).
267Forstructuralmetadata,itispossibletoinstructthewebservicetoresolvereferences268(forinstance,whenqueryingfordatastructuredefinitions,itispossibletoalso269retrievetheconceptsandcodelistsusedinthereturneddatastructuredefinitions),270aswellasartefactsthatusethematchingartefact(forexample,toretrievethe271dataflowsthatuseamatchingdatastructuredefinition).
272Forstructuralmetadata,itispossibletoretrieveaminimalversionoftheartefact,for273thesakeofefficiency(forexample,toretrieveallcodelists–names,ids,etc–274withoutthecodes).
275Adistinctionshouldbeestablishedbetweentheelementsthatallowidentifyingthe276resourcetoberetrievedandtheelementsthatgiveadditionalinformationabout,or277allowtofurtherfilter,thedesiredresults.
Elementsbelongingtothe1stcategoryare278specifiedinthepathpartoftheURLwhileelementsbelongingtothe2ndcategoryare279specifiedinthequerystringpartoftheURL.
2804.
3StructuralMetadataQueries2814.
3.
1Resources282Thefollowingresourcesaredefined:283datastructure2284metadatastructure3285categoryscheme286conceptscheme287codelist288hierarchicalcodelist289organisationscheme4290agencyscheme52912ThishasbeenshortenedfromDataStructureDefinitiontoallowforshorterURLs.
3ThishasbeenshortenedfromMetadataStructureDefinitiontoallowforshorterURLs.
4Theorganisationschemeresourcecanbeusedwhenevertheroleplayedbytheorganisationschemes(e.
g.
maintenanceagencies)isnotknown/relevant.
13dataproviderscheme292dataconsumerscheme293organisationunitscheme294dataflow295metadataflow296reportingtaxonomy297provisionagreement298structureset299process300categorisation301contentconstraint302attachmentconstraint303structure63044.
3.
2Parameters3054.
3.
2.
1Parametersusedforidentifyingaresource306Thefollowingparametersareusedforidentifyingresources:307ParameterTypeDescriptionagencyIDAstringcompliantwiththeSDMXcommon:NCNameIDTypeTheagencymaintainingtheartefacttobereturnedresourceIDAstringcompliantwiththeSDMXcommon:IDTypeTheidoftheartefacttobereturnedversionAstringcompliantwiththeSDMXcommon:VersionTypeTheversionoftheartefacttobereturnedTheparametersmentionedabovearespecifiedusingthefollowingsyntax:308protocol://ws-entry-point/resource/agencyID/resourceID/version309Furthermore,somekeywordsmaybeused:310KeywordScopeDescriptionall7agencyIDReturnsartefactsmaintainedbyanymaintenanceagencyallresourceIDReturnsallresourcesofthetypedefinedbytheresourceparameter85For3ofthesubtypesofOrganisationScheme(AgencyScheme,DataProviderSchemeandDataConsumerScheme),theidandversionparametershavefixedvalues.
SeeSection03oftheSDMXinformationmodeldocumentforadditionalinformation.
6Thistypecanbeusedtoretrieveanytypeofstructuralmetadatamatchingthesuppliedparameters.
7As"all"isareservedkeywordintheSDMXRESTfulAPI,itisrecommendednottouseitasanidentifierforagencies,resourcesoraspecificversion.
8Default,ifparameternotspecified14allversionReturnsallversionsoftheresourcelatestversionReturnsthelatestversioninproductionoftheresource311Thefollowingrulesapply:312Ifnoversionisspecified,theversioncurrentlyusedinproductionshouldbereturned.
313Itisthereforeequivalenttousingthekeyword"latest".
314IfnoagencyIDisspecified,thematchingartefactsmaintainedbyanymaintenance315agencyshouldbereturned.
Itisthereforeequivalenttousingthekeyword"all"9.
316IfnoresourceIDisspecified,allmatchingartefacts(accordingtotheothercriteria317used)shouldbereturned.
It'sisthereforeequivalenttousingthekeyword"all".
318Ifnoparametersarespecified,the"latest"versionof"all"resourcesofthetype319identifiedbytheresourceparameter,maintainedbyanymaintenanceagencyshould320bereturned.
3214.
3.
2.
2Parametersusedtofurtherdescribethedesiredresults322Thefollowingparametersareusedtofurtherdescribethedesiredresults,oncetheresource323hasbeenidentified.
Asmentionedin3.
2,theseparametersappearinthequerystringpartof324theURL.
325ParameterTypeDescriptionDefaultdetailStringThisattributespecifiesthedesiredamountofinformationtobereturned.
Forexample,itispossibletoinstructthewebservicetoreturnonlybasicinformationaboutthemaintainableartefact(i.
e.
:id,agencyid,versionandname).
Mostnotably,itemsofitemschemeswillnotbereturned(forexample,itwillnotreturnthecodesinacodelistquery).
Possiblevaluesare:"allstubs"(allartefactsshouldbereturnedasstubs10),"referencestubs"(referencedartefactsshouldbereturnedasstubs11)andfull(allavailableinformationforallartefactsshouldbereturned12)13.
fullreferencesStringThisattributeinstructsthewebservicetoreturn(ornot)theartefactsreferencedbytheartefacttobereturned(forexample,thecodelistsandconceptsusedbythedatastructuredefinitionmatchingthequery),asnone9Thiswouldpotentiallyreturnmorethanoneartefact,ifdifferentagenciesgivethesameidentifiertoaresource(forexample,http://ws-entry-point/codelist/all/CL_FREQ,couldreturnmorethanonecodelistifmorethanoneagencyismaintainingacodelistwithid"CL_FREQ").
10TheequivalentinSDMX-MLqueryis:StubatthequerylevelandStubatthereferencelevel.
11TheequivalentinSDMX-MLqueryis:FullatthequerylevelandStubatthereferencelevel.
12TheequivalentinSDMX-MLqueryis:FullatthequerylevelandFullatthereferencelevel.
13Incaseastubisreturned,theisExternalReferenceattributeofthereturnedartefact(s)shouldbesetto"true"andthelocationwherethefullversionoftheartefact(s)canbedownloadedshouldbespecifiedinthestructureURLattribute.
15wellastheartefactsthatusethematchingartefact(forexample,thedataflowsthatusethedatastructuredefinitionmatchingthequery).
Possiblevaluesare:"none"(noreferenceswillbereturned),"parents"(theartefactsthatusetheartefactmatchingthequery),"parentsandsiblings"(theartefactsthatusetheartefactmatchingthequery,aswellastheartefactsreferencedbytheseartefacts),"children"(artefactsreferencedbytheartefacttobereturned),"descendants"(referencesofreferences,uptoanylevel,willalsobereturned),"all"(thecombinationofparentsandsiblingsanddescendants).
Inaddition,aconcretetypeofresource,asdefinedin3.
3.
1,mayalsobeused(forexample,references=codelist).
4.
3.
2.
3Applicabilityandmeaningofreferencesattribute326Thetablebelowliststhe1stlevelartefacts(onelevelup,oneleveldown)thatwillbereturned327ifthereferencesparameterissetto"all".
Artefactsreferencedbythematchingartefactare328displayedinregularstyle,whiletheartefactsthatreferencethematchingartefactare329displayedinItalic.
330MaintainableartefactArtefactsreturnedAgencySchemeCategorisationProcessMetadataStructureDefinitionStructureSetCategorisationAllCategorySchemeCategorisationProcessStructureSetCodelistCategorisationProcessHierarchicalCodelistConceptSchemeDataStructureDefinitionMetadataStructureDefinitionStructureSetConceptSchemeCategorisationProcessCodelistDataStructureDefinitionMetadataStructureDefinitionStructureSetConstraintCategorisationProcessDataProviderSchemeDataStructureDefinition16DataflowMetadataStructureDefinitionMetadataflowProvisionAgreementDataConsumerSchemeCategorisationProcessMetadataStructureDefinitionStructureSetDataflowCategorisationProcessConstraintDataStructureDefinitionProvisionAgreementReportingTaxonomyStructureSetDataProviderSchemeCategorisationProcessConstraintProvisionAgreementMetadataStructureDefinitionStructureSetDataStructureDefinitionCategorisationProcessCodelistConceptSchemeConstraintDataflowStructureSetHierarchicalCodelistCategorisationProcessCodelistStructureSetMetadataflowCategorisationProcessConstraintMetadataStructureDefinitionProvisionAgreementReportingTaxonomyStructureSetMetadataStructureDefinitionCategorisationProcessConceptSchemeCodelistDataProviderSchemeDataConsumerSchemeAgencySchemeOrganisationUnitSchemeConstraintMetadataflow17StructureSetOrganisationUnitSchemeCategorisationProcessConstraintMetadataStructureDefinitionStructureSetProcessAllProvisionAgreementCategorisationProcessDataProviderSchemeDataflowMetadataflowConstraintReportingTaxonomyCategorisationProcessDataflowMetadataflowStructureSetStructureSetCategorisationProcessDataStructureDefinitionMetadataStructureDefinitionCategorySchemeDataProviderSchemeDataConsumerSchemeAgencySchemeOrganisationUnitSchemeConceptSchemeCodelistReportingTaxonomyHierarchicalCodelistDataflowMetadataflow4.
3.
3Examples331332-Toretrieveversion1.
0oftheDSDwithidECB_EXR1maintainedbytheECB,aswellasthe333codelistsandtheconceptsusedintheDSD:334http://ws-entry-point/datastructure/ECB/ECB_EXR1/1.
0references=children335-ToretrievethelatestversioninproductionoftheDSDwithidECB_EXR1maintainedbythe336ECB,withoutthecodelistsandconceptsoftheDSD:337http://ws-entry-point/datastructure/ECB/ECB_EXR1338-ToretrieveallDSDsmaintainedbytheECB,aswellasthedataflowsusingthese339DSDs:34018http://ws-entry-point/datastructure/ECBreferences=dataflow341-Toretrievethelatestversioninproductionofallcodelistsmaintainedbyallmaintenance342agencies,butwithoutthecodes:343http://ws-entry-point/codelistdetail=allstubs344-Toretrieve,asstubs,thelatestversioninproductionofallmaintainableartefactsmaintained345bytheECB:346http://ws-entry-point/structure/ECBdetail=allstubs347348194.
4DataandMetadataQueries3494.
4.
1Resources350Thefollowingresourcesshouldbesupported:351data352metadata3534.
4.
2Parameters3544.
4.
2.
1Parametersusedforidentifyingaresource355Thefollowingparametersareusedforidentifyingresourcesindataqueries:356ParameterTypeDescriptionflowRef14Astringidentifyingthedataflow.
Thesyntaxisagencyid,artefactid,version,separatedbya",".
Forexample:AGENCY_ID,FLOW_ID,VERSIONIncasethestringonlycontainsoneoutofthese3elements,itisconsideredtobetheflowid,i.
e.
all,FLOW_ID,latestIncasethestringonlycontainstwooutofthese3elements,theyareconsideredtobetheagencyidandtheflowid,i.
e.
AGENCY_ID,FLOW_ID,latestThedata(ormetadata)flowofthedata(ormetadata)tobereturnedkeyAstringcompliantwiththeKeyTypedefinedintheSDMXWADL.
Thekeyoftheartefacttobereturned.
Wildcardingissupportedbyomittingthedimensioncodeforthedimensiontobewildcarded.
Forexample,ifthefollowingserieskeyidentifiesthebilateralexchangeratesforthedailyUSdollarexchangerateagainsttheeuro,D.
USD.
EUR.
SP00.
A,thenthefollowingserieskeycanbeusedtoretrievethedataforallcurrenciesagainsttheeuro:D.
.
EUR.
SP00.
A.
TheORoperatorissupportedusingthe+character.
Forexample,thefollowingserieskeycanbeusedtoretrievetheexchangeratesagainsttheeuroforboththeUSdollarandtheJapaneseYen:14It'sacommonusecaseinSDMX-basedwebservicesthattheflowidissufficienttouniquelyidentifyadataflow.
Shouldthisnotbethecase,theagencyidandthedataflowversion,canbeused,inconjunctionwiththeflowid,inordertouniquelyidentifyadataflow.
20D.
USD+JPY.
EUR.
SP00.
A.
providerRef15Astringidentifyingtheprovider.
Thesyntaxisagencyid,providerid,separatedbya",".
Forexample:AGENCY_ID,PROVIDER_ID.
Incasethestringonlycontainsoneoutofthese2elements,itisconsideredtobetheproviderid,i.
e.
all,PROVIDER_ID.
Theproviderofthedata(ormetadata)toberetrieved.
Ifnotsupplied,thereturnedmessagewillcontaindata(ormetadata)providedbyanyprovider.
357Theparametersmentionedabovearespecifiedusingthefollowingsyntax:358protocol://ws-entry-point/resource/flowRef/key/providerRef359Furthermore,somekeywordsmaybeused:360KeywordScopeDescriptionallkeyReturnsalldatabelongingtothespecifieddataflowandprovidedbythespecifiedprovider.
all16providerRefReturnsalldatamatchingthesuppliedkeyandbelongingtothespecifieddataflowthathasbeenprovidedbyanydataprovider.
361Thefollowingrulesapply:362Ifnokeyisspecified,alldata(ormetadata)belongingtothedataflow(or363metadataflow)identifiedbytheflowRefshouldbesupplied.
Itisthereforeequivalent364tousingthekeyword"all".
365IfnoproviderRefisspecified,thematchingdata(ormetadata)providedbyanydata366providershouldbereturned.
Itisthereforeequivalenttousingthekeyword"all".
3674.
4.
2.
2Parametersusedtofurtherfilterthedesiredresults368Thefollowingparametersareusedtofurtherdescribe(orfilter)thedesiredresults,oncethe369resourcehasbeenidentified.
Asmentionedin3.
2,theseparametersgointhequerystring370partoftheURL.
371ParameterTypeDescriptionstartPeriodcommon:StandardTimePeriodType,asdefinedintheThestartperiodforwhichresultsshouldbesupplied15It'sacommonusecaseinSDMX-basedwebservicesthattheprovideridissufficienttouniquelyidentifyadataprovider.
Shouldthisnotbethecase,theagencycanbeused,inconjunctionwiththeproviderid,inordertouniquelyidentifyadataprovider.
16As"all"isareservedkeywordintheSDMXRESTfulAPI,itisrecommendednottouseitasanidentifierforproviders.
21SDMXCommon.
xsdschema.
Canbeexpressedusing17:dateTime:alldatathatfallsbetweenthecalendardateswillbematchedGregorianPeriod:alldatathatfallsbetweenthecalendardateswillbematchedReportingPeriod:alldatareportedasperiodsthatfallbetweenthespecifiedperiodswillbereturned.
Whencomparingreportingweeksanddaystohigherorderperiods(e.
g.
quarters)onemustaccountfortheactualtimeframescoveredbytheperiodstodeterminewhetherthedatashouldbeincluded.
DatareportedasGregorianperiodsordistinctrangeswillbereturnedifitfallsbetweenthespecifiedreportingperiods,basedonareportingyearstartdayofJanuary1.
Incasethe:or+charactersareused,theparametermustbepercent-encodedbytheclient18.
Notethatthisvalueisassumedtobeinclusivetotherangeofdatabeingsought.
(inclusive).
endPeriodSameasaboveTheendperiodforwhichresultsshouldbesupplied(inclusive).
updatedAfterxs:dateTimeThelasttimethequerywasperformedbytheclientinthedatabase.
Ifthisattributeisused,thereturnedmessageshouldonlyincludethelatest17Foradditionalinformation,seesection4.
2.
14ofSection06(SDMXTechnicalNotes).
18Seehttp://en.
wikipedia.
org/wiki/URL_encoding#Percent-encoding_reserved_charactersforadditionalinformation.
22versionofwhathaschangedinthedatabasesincethatpointintime(updatesandrevisions).
Thisshouldinclude:-Observations19thathavebeenaddedsincethelasttimethequerywasperformed(INSERT).
-Observationsthathavebeenrevisedsincethelasttimethequerywasperformed(UPDATE).
-Observationsthathavebeendeletedsincethelasttimethequerywasperformed(DELETE).
Ifnooffsetisspecified,defaulttolocaltimeofthewebservice.
firstNObservationsPositiveintegerIntegerspecifyingthemaximumnumberofobservationstobereturnedforeachofthematchingseries,startingfromthefirstobservationlastNObservationsPositiveintegerIntegerspecifyingthemaximumnumberofobservationstobereturnedforeachofthematchingseries,countingbackfromthemostrecentobservationdimensionAtObservationAstringcompliantwiththeSDMXcommon:NCNameIDTypeTheIDofthedimensiontobeattachedattheobservationlevel.
Thisparameterallowstheclienttoindicatehowthedatashouldbepackagedbytheservice.
Theoptionsare"TIME_PERIOD"(atimeseriesviewofthedata),theIDofanyother19Iftheinformationaboutwhenthedatahasbeenupdatedisnotavailableattheobservationlevel,thewebserviceshouldreturneithertheseriesthathavechanged(iftheinformationisattachedattheserieslevel)orthedataflowsthathavechanged(iftheinformationisattachedatthedataflowlevel).
23dimensionusedinthatdataflow(across-sectionalviewofthedata)orthekeyword"AllDimensions"(a"flat"viewofthedatawheretheobservationsaregroupedneitherbytimenorbyanon-timecrosssection).
Incasethisparameterisnotset,theserviceisexpectedto:-DefaulttoTimeDimension,ifthedatastructuredefinitionhasone;-Ifnot,defaulttoMeasureDimension,ifthedatastructuredefinitionhasone;-Ifnoneoftheaboveistrue,defaulttoAllDimensions.
detailStringThisattributespecifiesthedesiredamountofinformationtobereturned.
Forexample,itispossibletoinstructthewebservicetoreturndataonly(i.
e.
noattributes).
Possibleoptionsare:"full"(alldataanddocumentation,includingannotations-Thisisthedefault),"dataonly"(attributes–andthereforegroups–willbeexcludedfromthereturnedmessage),"serieskeysonly"(returnsonlytheserieselementsandthedimensionsthatmakeuptheserieskeys.
Thisisusefulforperformancereasons,toreturntheseriesthatmatchacertainquery,withoutreturningtheactualdata),"nodata"(returnsthegroupsandseries,includingattributesandannotations,withoutobservations).
37224Thetablebelowdefinesthemeaningofparameterscombinations:373startPeriodwithnoendPeriodUntilthemostrecentendPeriodandnostartPeriodFromthebeginningstartPeriodandendPeriodWithinthesuppliedtimerangelastNObservations+startPeriod/endPeriodThespecifiednumberofobservations,startingfromtheend,withinthesuppliedtimerangefirstNObservations+startPeriod/endPeriod+updatedAfterDateThespecifiednumberofobservations,startingfromthebeginning,thathavechangedsincethesuppliedtimestamp,withinthesuppliedtimerangeupdatedAfterDate+startPeriod/endPeriodTheobservations,withinthesuppliedtimerange,thathavechangedsincethesuppliedtimestamp.
4.
4.
3Examples374ToretrievethedatafortheseriesM.
USD.
EUR.
SP00.
AsuppliedbytheECBforthe375ECB_EXR1_WEBdataflow:376http://ws-entry-point/data/ECB_EXR1_WEB/M.
USD.
EUR.
SP00.
A/ECB377Inthisexample,theassumptionismadethatthedataflowid(ECB_EXR1_WEB)is378sufficienttouniquelyidentifythedataflow,andthedataproviderid(ECB)issufficient379touniquelyidentifythedataprovider.
380Toretrievethedata,providedbytheECBfortheECB_EXR1_WEBdataflow,forthe381suppliedserieskeys,usingwildcardingfortheseconddimension:382http://ws-entry-point/data/ECB,ECB_EXR1_WEB,latest/M.
.
EUR.
SP00.
A/ECB383Inthisexample,thefullreferencetothedataflowissupplied(ECBasmaintenance384agency,ECB_EXR1_WEBasdataflowidandlatestfortheversion).
385Toretrievetheupdatesandrevisionsforthedatamatchingthesuppliedserieskeys,386usingtheORoperatorfortheseconddimension,andusingpercentencodingforthe387updatedAfterDate:388http://ws-entry-389point/Data/ECB_EXR1_WEB/M.
USD+GBP+JPY.
EUR.
SP00.
AupdatedAfter=2390009-05-15T14%3A15%3A00%2B01%3A00391Toretrievethedatamatchingthesuppliedserieskeyandrestrictingthestartandend392dates:393http://ws-entry-394point/data/ECB_EXR1_WEB/D.
USD.
EUR.
SP00.
AstartPeriod=2009-05-39501&endPeriod=2009-05-313964.
5Schemaqueries3974.
5.
1Resources398Thefollowingresourceisdefined:39925schema400401ThisresourceallowsaclienttoaskaservicetoreturnanXMLschema,whichdefinesdata402(orreferencemetadata)validitywithinacertaincontext.
Theservicemusttakeintoaccount403theconstraintsthatapplywithinthatcontext(DSDorMSD,dataflowormetadataflow,or404provisionagreement).
4054.
5.
2Parameters4064.
5.
2.
1Parametersusedforidentifyingaresource407Thefollowingparametersareusedforidentifyingresources:408ParameterTypeDescriptioncontextOneofthefollowing:datastructure,metadatastructure,dataflow,metadatafloworprovisionagreement.
Thevalueofthisparameterdeterminestheconstraintsthatneedtobetakenintoaccount,whengeneratingtheschema.
Ifdatastructureormetadatastructureisused,constraintsattachedtotheDSDorMSDmustbeappliedwhengeneratingtheschema.
Ifdataflowormetadataflowisused,constraintsattachedtothedataflowormetadataflowandtotheDSDorMSDusedinthedataflowormetadataflowmustbeappliedwhengeneratingtheschema.
Ifprovisionagreementisused,constraintsattachedtotheprovisionagreement,aswellastothedataflowormetadafalowusedintheagreementandtheDSDorMSDusedinthedataflowormetadataflowmustbeappliedwhengeneratingtheschema.
agencyIDAstringcompliantwiththeSDMXcommon:NCNameIDTypeTheagencymaintainingtheartefactusedtogeneratetheschematobereturned.
resourceIDAstringcompliantwiththeSDMXcommon:IDTypeTheidoftheartefactusedtogeneratetheschematobereturned.
versionAstringcompliantwiththeSDMXcommon:VersionTypeTheversionoftheartefactusedtogeneratetheschematobereturned.
Theparametersmentionedabovearespecifiedusingthefollowingsyntax:409protocol://ws-entry-point/schema/context/agencyID/resourceID/version410Furthermore,akeywordmaybeused20:411KeywordScopeDescription20Asthequeryforschemamustmatchoneartefactonly,thekeyword"all"isnotsupportedforagencyIdandresourceId.
26latestversionReturnsthelatestversioninproductionoftheresource412Thefollowingrulesapply:413Ifnoversionattributeisspecified,theversioncurrentlyusedinproductionshouldbe414returned.
Itisthereforeequivalenttousingthekeyword"latest".
4154.
5.
2.
2Parametersusedtofurtherdescribethedesiredresults416Thefollowingparametersareusedtofurtherdescribethedesiredresults,oncetheresource417hasbeenidentified:418ParameterTypeDescriptiondimensionAtObservationAstringcompliantwiththeSDMXcommon:NCNameIDTypeTheIDofthedimensiontobeattachedattheobservationlevel.
explicitMeasureBooleanForcross-sectionaldatavalidation,indicateswhetherobservationsarestronglytyped(defaultstofalse).
4.
5.
3Examples419420-Toretrievetheschemafordatasuppliedwithinthecontextofversion1.
0oftheprovision421agreementEXR_WEBmaintainedbytheECB:422http://ws-entry-point/schema/provisionagreement/ECB/EXR_WEB/1.
0/423Inthiscase,theschemareturnedbytheservicemusttakeintoaccountthe424constraintsattachedtotheprovisionagreement,thedataflowusedintheprovision425agreementandthedatastructuredefinitionusedinthedataflow.
4264.
6SelectionoftheAppropriateRepresentation427Selectionoftheappropriateformatsfortheresponsemessageismadeusingthe428mechanismsdefinedforHTTPContentNegotiation21.
UsingtheHTTPContentNegotiation429mechanism,theclientspecifiesthedesiredformatandversionoftheresourceusingthe430AcceptHTTPheader22.
431Alongwithofficialmimetypes(e.
g.
:text/html,application/xml,etc),thestandardalsodefines432asyntaxallowingaservicetodefineitsowntypes.
TheSDMXRestfulAPImakesuseofthis433functionalityandthesyntaxisasfollows:43421Foradditionalinformation,pleaserefertohttp://www.
w3.
org/Protocols/rfc2616/rfc2616-sec12.
html22Foradditionalinformation,pleaserefertohttp://www.
w3.
org/Protocols/rfc2616/rfc2616-sec14.
html27application/vnd.
sdmx.
[format]+xml;version=[version23],where[format]shouldbereplacedwith435thedesiredformat(i.
e.
:genericdata,structurespecificdata,structure,etc)and[version]436shouldbereplacedwithoneoftheversionsoftheSDMXstandard,startingwithSDMX2.
1437(e.
g.
:2.
1,futureSDMXversions,etc).
438Afewexamplesarelistedbelow439SDMX-MLGenericDataFormat,version2.
1:440application/vnd.
sdmx.
genericdata+xml;version=2.
1441SDMX-MLStructureSpecificDataFormat,version2.
1:442application/vnd.
sdmx.
structurespecificdata+xml;version=2.
1443SDMX-MLStructureFormat,version2.
1:444application/vnd.
sdmx.
structure+xml;version=2.
1445446Incasetheclientdoesnotspecifythedesiredformatandversionoftheresponsemessage,447oronlyspecifiesthegenericapplication/xmlformat,theSDMXRESTfulwebserviceshould448return:449Themostrecentversion,thattheservicesupports,oftheSDMX-MLStructureformat450forstructuralmetadataqueries;451Themostrecentversion,thattheservicesupports,oftheSDMX-MLGenericData452formatfordataqueries;453Themostrecentversion,thattheservicesupports,oftheSDMX-MLGeneric454Metadataformatformetadataqueries.
455456ThelistbelowindicatesthevalidformatsforSDMXRESTfulwebservices,compliantwith457version2.
1oftheSDMXstandard:458application/vnd.
sdmx.
genericdata+xml;version=2.
1459application/vnd.
sdmx.
structurespecificdata+xml;version=2.
1460application/vnd.
sdmx.
generictimeseriesdata+xml;version=2.
1461application/vnd.
sdmx.
structurespecifictimeseriesdata+xml;version=2.
1462application/vnd.
sdmx.
genericmetadata+xml;version=2.
1463application/vnd.
sdmx.
structurespecificmetadata+xml;version=2.
1464application/vnd.
sdmx.
structure+xml;version=2.
1465application/vnd.
sdmx.
schema+xml;version=2.
14664.
7Enablingdatacompression467CompressionshouldbeenabledusingtheappropriateHTTPHeaderfield(Accept-468Encoding).
4695StandardErrorsforSDMXWebServices4705.
1Introduction471InSDMX-MLversion2.
1anerrorelementhasbeenimplementedinallmessagesthatwould472normallybearesponsetoaquery,thatis:Structure,MetadataStructure,GenericData,473DSDDataandMetadata.
Incaseofanerrortheerrorelementwillbeaddedtothe474structure:Structures|generic:GenericDataSet|message:DataSet|47523Forthetimebeing,onlyversion2.
1issupportedasversionnumber.
28genericmetadata:MetadataSet|metadatareport:MetadataSetelementintheresponse476message.
477TheelementbelongstoMessageschemasandusetheStatusTextTypefromtheCommon478schemafile.
Intheendofthisdocumentisanextractfromtheschemafilesshowingtheerror479element.
480TheerrorpartoftheXMLmessagesupportsthe2followingusecases:481AnyerrorwhichisdetectedbeforeSDMXdataisstreamedtotheclientwillbe482returnedintheErrorelementdefinedintheSDMXmessagenamespace.
483IftheerroroccursaftersomeSDMXdatahasalreadybeenstreamedtotheclient,484theerrorinformationwillbesuppliedviaa"footer"elementintheSDMXpayload.
4855.
2ErrorhandlinginRESTWebService486RESTfulwebservicesshouldindicateerrorsusingtheproperHTTPstatuscode.
Inaddition,487wheneverappropriate,theerrorshouldalsobereturnedusingtheerrormessageoffered488startingwithversion2.
1ofSDMX-ML.
4895.
3SOAPWebService490SOAPwebservicesshouldindicateerrorsusingthestandardSOAPerrormechanism,using491thespecificnamespacecreatedforthispurpose.
Inaddition,wheneverappropriate24,the492errorshouldalsobereturnedusingtheerrormessageofferedstartingwithversion2.
1of493SDMX-ML.
494Incaseoferror,thefollowingelementsshouldbesetintheSOAPEnvelope:495theelementfortheerrornumber496theelementforthedescription497theelementforthewebservicemethodwiththeurlforthewebservice498prefixed499Theelementisoptional,andcanbeusedbytheserviceprovidertoprovide500anyadditionalinformationdeemeduseful5015.
4Errorcategories502Thenumberingoferrormessagesdividesthethreetypesofmessagesup,andprovidesfor503webservicestoimplementcustommessagesaswell:504000–499:Client-caused"errors"505500–999:Server-caused"errors"5061000andup:CustomMessages5075.
5Client-CausedErrors5085.
5.
1Noresultsfound–100509ThereisnodifferencebetweenSOAPandRESTwebservicesforthismessage.
Iftheresult510fromthequeryisemptythewebserviceshouldreturnthismessage.
Thisisawaytoinform511theclientthattheresultisempty.
51224AccordingtotheSOAPversionFramework1.
2,itisnotpossibletoplacebothaelementandreturnotherinformation.
295.
5.
2Unauthorized–110513Forusewhenauthenticationisneededbuthasfailedorhasnotyetbeenprovided.
5145.
5.
3ResponseTooLargeDuetoClientRequest130515Therequestresultsinaresponsethatislargerthantheclientiswillingorabletoprocess.
516Theclienthasthepossibility,usingSDMX-MLquery,tolimitthesizeoftheresponsereturned517bytheserver.
Incasetheresponseislargerthanthelimitsetbytheclient,theservershould518returnthiserrorcode.
5195.
5.
4Syntaxerror–140520Thiserrorcodeisusedwhen:521-SOAP:ThesuppliedSDMX-MLQuerymessageisinvalid(XMLvalidationfails)522-REST:Thequerystringdoesn'tcomplywiththeSDMXRESTfulinterface.
5235.
5.
5Semanticerror–150524Awebserviceshouldreturnthiserrorwhenarequestissyntacticallycorrectbutfailsa525semanticvalidationorviolatesagreedbusinessrules.
5265.
6Server-CausedErrors5275.
6.
1InternalServerError–500528Thewebserviceshouldreturnthiserrorcodewhennoneoftheothererrorcodesbetter529describesthereasonforthefailureoftheservicetoprovideameaningfulresponse.
5305.
6.
2Notimplemented–501531IfthewebservicehasnotyetimplementedoneofthemethodsdefinedintheAPI,thenthe532webserviceshouldreturnthiserror.
533Note:AllSDMXwebservicesshouldimplementallthestandardinterfaces,eveniftheironly534functionistoreturnthiserrormessage.
ThiseasesinteroperabilitybetweenSDMX-compliant535webservicesanditalsoeasesthedevelopmentofgenericSDMXwebservicesclients.
5365.
6.
3Serviceunavailable–503537Ifawebserviceistemporarilyunavailablebecauseofmaintenanceorforsomeothersimilar538reasons,thenthewebserviceshouldreturnthiserrorcode.
5395.
6.
4Responsesizeexceedsservicelimit-510540Therequestresultsinaresponsethatislargerthantheserveriswillingorabletoprocess.
541Incasetheserviceoffersthepossibilitytouserstodownloadtheresultsoflargequeriesata542laterstage(forinstance,usingasynchronouswebservices),thewebservicemaychooseto54330indicatethe(future)locationofthefile,aspartoftheerrormessage.
InSOAP,thiscanbe544doneusingtheerrorelement.
5455.
7CustomErrors–1000+546Webservicescanusecodes1000andaboveforthetransmissionofservice-specificerror547messages.
However,itshouldbeunderstoodthatdifferentservicesmayusethesame548numbersfordifferenterrors,sothedocumentationprovidedbythespecificserviceshouldbe549consultedwhenimplementingthisclassoferrors.
5505.
8SDMXtoHTTPErrorMapping551ThefollowingtablemapstheSDMXerrorcodeswiththeHTTPstatuscodeforRESTfulweb552servicesandindicateshowtheerrorsshouldbereturnedinSOAP.
553SDMXerrorHTTPerrorusageinRESTSOAPusageClienterrors100Noresultsfound404NotfoundSOAPFault110Unauthorized401UnauthorizedSOAPFault130Responsetoolargeduetoclientrequest413RequestentitytoolargeSOAPFault140Syntaxerror400BadsyntaxSOAPFault150Semanticerror400BadsyntaxSOAPFaultServererrors500InternalServererror500InternalservererrorSOAPFault501Notimplemented501NotimplementedSOAPFault503Serviceunavailable503ServiceunavailableSOAPFault510Responsesizeexceedsservicelimit413RequestentitytoolargePayload1000+500InternalservererrorSOAPFault316Annex:Examples5546.
1SampleQueriesforaWebServicesClient5556.
1.
1Step1:BrowsinganSDMXdatasource,usingalistofsubject-556matterdomains5576.
1.
1.
1Usecase558Thewebclientoffersthepossibilitytoretrievedatabybrowsingalistofsubjectmatter559domains.
TheclientrequeststheversioncurrentlyinproductionoftheSDW_ECONcategory560scheme,maintainedbytheECB.
5615626.
1.
1.
2RequestusingtheRESTfulAPI563http://ws-entry-point/categoryscheme/ECB/SDW_ECONreferences=categorisation564Note:Usingthereferencesattributewithavalueof"categorisation",thecategorisationsused565bythecategoryschemewillalsobereturnedandthesewillcontainreferencestothe566dataflowsattachedtothecategories.
5676.
1.
1.
3RequestusingtheSOAPAPI56856957057157257332SDW_ECON574ECB575576577578Note:Forthesakeofclarity,theSOAPenvelopehasbeenomitted.
5796.
1.
1.
4Response580AnSDMX-MLStructuremessagecontainingthecategoryschemes,aswellasthe581categorisationswithreferencestothedataflowswillbereturned.
ThestructureoftheSDMX-582MLStructuremessagewillbeasfollow(rootelement,headerandrepeatedelementsomitted583forthesakeofclarity):5845855865875885895905915925935946.
1.
2STEP2:Selectingadataflow5956.
1.
2.
1Usecase596Onceasubject-matterdomainandadataflowhavebeenselected,afilterboxneedstobe597populated,toallowuserstoselectdata.
Inordertoonlycreatequeriesfordatathatactually598existinthedatabase,thedataflowconstraintswillalsoberequested.
599336006.
1.
2.
2RequestusingtheRESTfulAPI601Inthissamplequery,thedataflowidis123456,theagencyidisECBandtheversionis1.
2.
602Usingthereferencesattribute,thedatastructuredefinitionandtheconstraintswillalsobe603returned.
604http://ws-entry-point/dataflow/ECB/123456/1.
2references=all6056.
1.
2.
3RequestusingtheSOAPAPI6066076086096106111234566121.
2613ECB6146156166.
1.
2.
4Response617AnSDMX-MLStructuremessagecontainingtherequesteddataflow,aswellasthedata618structuredefinitionandthedataflowconstraintsattached.
ThestructureoftheSDMX-ML619Structuremessagewillbeasfollows(rootelementandheaderomitted):62034621622623624625626627628629630631632633634635636637If,beforeselectingdata,theuserwantstoreviewthedatastructuredefinitionusedbythe638dataflow,thiscanbedonewithoutsendinganadditionalquery,asthisinformationhas639alreadybeenincludedintheresponse.
640641356.
1.
3STEP3:Dataselection6426.
1.
3.
1Usecase643Theuserusesthedimensionfilters,toretrievethedataheisinterestedin.
6446456.
1.
3.
2RequestusingtheRESTfulAPI646http://ws-entry-point/data/123456/M.
I4.
N.
9.
339+340+341.
N.
A1.
A/ECBstartPeriod=2009-64701&endPeriod=2009-12&detail=dataonly648Note:Apartfromthedataflowid(123456),thedataproviderissettoECB,andtheserieskey649usestheORoperatorforthe5thdimension.
Furthermore,onlydatafor2009shouldbe650returned.
Asthepurposeofthereturneddataistobedisplayedonagraph,thedetaillevelis651settodataonly.
Therefore,attributesandgroupswillbeexcludedfromthereturnedmessage.
652Regardingthereferencestothedataflow,theshortformisused,as,forthisparticularweb653service,thedataflowidandthedataprovideridaresufficienttouniquelyidentifythedataflow654andthedataproviderrespectively.
Shouldthisnotbethecase,thefullreferencemustbe655supplied(forexample,ECB+123456+1.
2insteadof123456).
6566.
1.
3.
3RequestusingtheSOAPAPI65765865966066136ECB662DataProviderScheme663664665ECB666667668669670671ECB6721234566731.
2674675676677678FREQ679M680681682REF_AREA683I4684685686ADJUSTMENT687N688689690DATA_TYPE_BOP6919692693694CURR_BRKDWN695N696697698COUNT_AREA699A1700701702SERIES_DENOM703A704705706TIME_PERIOD7072009-017092010-1271171271337714BOP_ITEM715339716717718BOP_ITEM719340720721722BOP_ITEM7233417247257267277286.
1.
3.
4Response729AnSDMX-MLGenericdatamessagecontainingtherequestedtimeseries.
730ThestructureoftheSDMX-MLDatamessagewillbeasfollows(rootelementandheader731omitted):7327337347357366.
2SampleErrorElementinanSDMXmessage737738739Errorisusedtocommunicate740thatanerrorhasoccurredwhenrespondingtoa741requestinannon-registryenvironment.
The742contentwillbeacollectionoferrormessages.
743744745746747748ErrorTypedescribesthe749structureofanerrorresponse.
750751752753755756ErrorMessage757containstheerrormessage.
Itcan75838occurmultipletimestocommunicate759messageformultipleerrors,orto760communicatetheerrormessagein761parallellanguages.
Ifbothmessages762formultipleerrorsandparallel763languagemessagesareused,theneach764errormessageshouldbegivenacode765inordertodistinguishmessagefor766uniqueerrors.
7677687697707717726.
3SoapFaultexample773774783784785sdmxerror:500786Internalservererror787sdmxws:GetCodelist7887897901028791792Couldnotgetconnectionfrompool793Couldnotgetconnectionfrompool794Couldnotgetconnectionfrompool795796SdmxRegistryServiceerror:couldnotgetconnectionfrom797pool798799800801802803397Annex:Securityguidelines804ThisannexdescribesusefulsecuritymeasuresforSDMXwebservices25.
8057.
1Authentication806Authenticationreferstotheprocessofuniquelyidentifyinganentity.
Inthecontextofaweb807service,serviceauthenticationandclientauthenticationaredistinct.
8087.
1.
1Serverauthentication809Clientsofwebserviceshaveahighinterestinensuringthattheyareconnectedtotheservice810theyintendtoconsumeandnottoarogueservicemasqueradingasatrustedentity.
To811supportthis,useSSL/TLS26andofferclientsthepossibilitytoconsumethewebserviceover812HTTPS.
8137.
1.
2Clientauthentication814Whenrestrictionsapplytothedataandmetadatapublished,itisimportantfortheservice815providertobeabletouniquelyidentifytheclient.
816ForRESTfulwebservices,supportthisrequirementbyusingHTTPbasicauthenticationover817SSL/TLS27.
Ifstrongerauthenticationisrequired,useSSLclientcertificatesinstead.
818HTTPbasicauthenticationoverSSL/TLScanalsobeusedtosupportauthenticationinSOAP819webservices.
Insituationswherethisisnotappropriate,useindustrystandardsuchas820OASISWebServicesSecurity(WSS)Specification.
Useanddeclareastandardtokenprofile821inWS-Policyassertions.
IncludeandexplicitlydeclareWSSecurityassertionsand822requirementstheWSDLfilewithastandardtargetednamespaceandsecuritytoken823information.
8247.
2Confidentiality825Confidentialityreferstotheprocessofguaranteeingthatresourcescannotbeaccessedby826unauthorisedusers.
827ThisrequirementisakeyrequirementfortheSDMXwebserviceswhenrestrictionsapplyto828thedataandmetadatapublished,asbothclientsandserviceshaveahighinterestin829ensuringtheirdataisnotillegallyaccessed.
Forthesewebservices,useSSL/TLS28to830supportconfidentialityduringthetransferbetweentheserviceandtheclientusing.
8317.
3Integrity832Integrityreferstotheprocessofguaranteeingthatresourcescannotbeaccidentallyor833maliciouslymodified.
83425Thisannexisnotcomprehensive,assecurity-relatedmeasuresforSDMXwebserviceswillvaryaccordingtothescopeofthewebserviceandthesecuritypoliciesoftheorganisationmaintainingthewebservice.
26Thisallowstheclienttovalidatethatthecertificatematchesthedomainnameoftheservice,isissuedbyatrustedauthority,andisnotexpired.
27SeeRFC2617foradditionalinformation.
28SSL/TLSsupportsthisrequirementusingacombinationofsymmetricandasymmetricencryption.
40SupportthisrequirementusingSSL/TLS29.
83529SSL/TLSsupportsthisrequirementbycalculatingamessagedigest.