Professional Documents
Culture Documents
0 APIOVERVIEW
2011APRIL11
EIDRAPIOverview
P a g e |2
Version1.0120110407
TABLEOFCONTENTS
1. DOCUMENTSCOPE.............................................................................................................................. 5 2. GENERALCONVENTIONS.................................................................................................................. 5
2.1 2.2 2.3 2.4 Errors ............................................................................................................................................................ 5 AsynchronousandImmediateCalls................................................................................................................ 7 BatchTransactions ........................................................................................................................................ 7 ModeSummary ............................................................................................................................................. 8
3. OBJECTS.................................................................................................................................................. 8
3.1 CreateandModify......................................................................................................................................... 8 3.1.1. CheatSheetObjectTypes ............................................................................................................................. 9 3.1.2. CheatSheetRelationships .......................................................................................................................... 10 3.1.3. Create............................................................................................................................................................. 12 3.1.4. AddingandRemovingRelationship ............................................................................................................... 12 3.1.5. ModifyingObjects.......................................................................................................................................... 14 3.1.6. Promote ......................................................................................................................................................... 14 3.1.7. Delete............................................................................................................................................................. 15 3.1.8. Alias................................................................................................................................................................ 15 3.1.9. RequestStatus ............................................................................................................................................... 16 3.2 ObjectInformation ...................................................................................................................................... 18 3.2.1. Resolution ...................................................................................................................................................... 19 3.2.2. Traversal......................................................................................................................................................... 21 3.2.3. Queries........................................................................................................................................................... 24 3.2.4. VirtualFields .................................................................................................................................................. 29 3.2.5. Provenance .................................................................................................................................................... 30
4. PARTIES,USERS,ANDPERMISSIONS......................................................................................... 30
4.1 Parties......................................................................................................................................................... 31 4.1.1. Create............................................................................................................................................................. 31 4.1.2. Modify............................................................................................................................................................ 32 4.1.3. AdministrativeTasks ...................................................................................................................................... 33 4.1.4. RetrievingInformation................................................................................................................................... 33 4.2 Permissions ................................................................................................................................................. 36
EIDRAPIOverview
P a g e |3
Version1.0120110407
5. UTILITIES............................................................................................................................................ 38
5.1 DOIProxy .................................................................................................................................................... 38
6. PREDEFINEDOBJECTSANDCONSTANTS ............................................................................... 39
6.1 6.2 6.3 6.4 Tombstones................................................................................................................................................. 39 Errorhandling.............................................................................................................................................. 39 PredefinedParties ...................................................................................................................................... 39 HandlePrefixes ........................................................................................................................................... 39
7. APPENDICES....................................................................................................................................... 40
7.1 SeasonsandEpisodes .................................................................................................................................. 40
7.2 ComplexInheritance.................................................................................................................................... 40 7.2.1. ResourceName............................................................................................................................................... 40 7.2.2. Languages ...................................................................................................................................................... 41 7.3 ModifyingObjects ....................................................................................................................................... 42
7.4 TextProcessing............................................................................................................................................ 42 7.2.3. FieldRules ...................................................................................................................................................... 42 7.2.4. LanguageSpecificFiltering ............................................................................................................................ 44 7.5 7.6 EscapingXMLCharacters ............................................................................................................................. 46 MappingEIDRfieldstoDOIfields................................................................................................................. 46
EIDRAPIOverview
P a g e |4
Version1.0120110407
1.
DOCUMENTSCOPE
ThisisanoverviewofthepublicandadministrativeAPIsforEIDR.Itdoesnotcover Deduplication(aninternalinterface) Bulkregistration(anAPIextensionprovidedbyanEIDRapplication) Analytics Lowleveldatabasemirroring.WiththisprivilegedAPIaclientcanrequestperiodicupdatesfrom theregistryandaskfordetailsofchangesmadeduringaparticulartimewindow.Thecombination ofthesetwoallowsforprimingacopyofthedataandthenkeepingituptodate,aswellastakinga simplesnapshotoftheregistryatanyparticularinstant.(Simplebulkreadofobjectscanbe implementedattheapplicationlevel.) Useraccountmanagement(thoughthismaybeincludedinafutureversionifthirdpartiesare allowedtodevelopapplicationsthatcreateaccounts)
TheregistryinterfaceitselfisRESTbased.ThisdocumentpresentsitasatraditionalproceduralAPI,suchas mightbeusedinaJavaorJavaScriptinterfacebuiltontopoftheunderlyingHTTPandXML.
2. GENERALCONVENTIONS
2.1 ERRORS Standarderrorsare: Authentication: Thesystemcouldnotauthenticatetheuserand/orgroupintherequest. Authorization:Therequesterisnotauthorizedtoperformtheaction,oraccessoneormoreof theDOIsintherequest RegistryReadOnly: TheRegistryisinreadonlymode.Iftheprimarysystemgoesdown,the mirrorsystemsarestillavailableforreading.Certainsystemadministrationtasks(synchronization withabackup,bulkexport,etc.)mayalsohavethisresult. SystemError:Theregistryisunabletodealwiththerequestforsomeinternalreason. 1 InvalidRequest: TherequestURLisinvalid,orcontainsunrecognizedorinvalidHTTPheaders, orcontainsunrecognizedorinvalidinformation.
In some cases these may set the registry into read-only mode until the problem is addressed.
EIDRAPIOverview
P a g e |5
Version1.0120110407
BadDOI:TherequestcontainsaDOIthatissyntacticallycorrectbuthasaninvalidchecksumoris notrecognizedbythesystem.SyntacticallymalformedDOIsgenerateaSyntaxError.Thebad DOIisincludedasadetail. SyntaxError:TheXMLintherequestdoesnotpassschemavalidation. ValidationError:TheXMLintherequestissyntacticallycorrectbutfailsothervalidationrules, ortherequestwouldresultinanobjectthatviolatesthevalidationrules,ortheobjectpassedinis inappropriateforthecall.Thedetailfieldcanbe: o IncompatibleCreationTypes:AcalltoGetModificationBase() failed becausemetadataneededfortherequestedtypeisnotpresentontheobject. NotRemovable: Returnedonfailedattempttoremovearelationship.Thiscan occureitherwhentherelationshipdoesnotexist,orwhenitsremovalwouldresultin aninvalidobjectorhierarchy. AliasNotAllowed: AnaliasedDOIwaspassedtoafunctionthatdoesntaccept aliases. IncompatibleAliasTarget:ADOIisbeingaliasedtoanincompatibleobject. NotInDev:thecallfailedbecauseanattemptwasmadetopromoteanobjectthat wasnotintheInDevstate.AlsoincludestheoffendingDOIasadetail.See Promote().
o o
Othererrorsare: BadToken:ThetokensenttoGetStatus()wasnotrecognized. BadQuery: Thequerystringwasmalformed. NoParent: TheobjectsenttoGetParent()isitselftherootofthetree. NoChildren: TheobjectsenttoGetChildren()isitselfaleafofthetree. ResultTooLong: AresultwastoolargetofitinaRESTresponse.Thiscanbecausedby requestingtoolargeapagesizeinqueries. DuplicateParty:ReturnedbyCreateParty()iftherequestistocreateaduplicateParty.The duplicatepartyisreturnedasadetail. DuplicateUser:ReturnedbyCreateUser()iftherequestistocreateaduplicateUser.The duplicateuserisreturnedasadetail. BadParty:ThepartyIDsubmittedaspartofarequestwasinvalid. BadUser:TheuserIDsubmittedaspartofarequestwasinvalid. P a g e |6 Version1.0120110407
EIDRAPIOverview
2.2 ASYNCHRONOUSANDIMMEDIATECALLS Callscanbeimmediate(theresultisreturnedimmediately)orasynchronous(thecallreturnsatokenwhich isusedtodiscoverthestatusoftherequest).Notallcallssupportasynchronousresults;thosethatdohave aflagintheinterfacespecifyingwhichmodetouse. Allcallsmustbeexplicitlyspecifiedasimmediateorasynchronous;thereisnodefaultingmechanism. Ingeneral,onlycallsthatrequireconfirmationfromthededuplicationsystemcanbeasynchronous. Create() Promote() AddRelationship() RemoveRelationship() RemoveSpecificRelationship() ReplaceRelationship() Modify()
EIDRAPIOverview
P a g e |7
Version1.0120110407
Batchable?
Yes Yes No No No No Yes Yes No No No
Mode
ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous ImmediateorAsynchronous Immediateonly Immediateonly Immediateonly Immediateonly
3. OBJECTS
3.1 CREATEANDMODIFY Objectsarecategorizedinfourways: Type:Typesareoftwosortsbasicandderived.TheBasicTypecoverstheminimalpossibleobject.It issufficientfordescribingawidevarietyofassets.DerivedTypesincludealltheinformationinthe BasicType,andaddextrainformationfordescribingmorecomplexobjects.TheDerivedTypesinEIDR areEdit,LanguageVariant,Series,Season,Episode,Composite,Clip,Encoding,andInteractiveMaterial.
EIDRAPIOverview
P a g e |8
Version1.0120110407
Relationships:Arelationshipisacasualtermforthewayinwhichtwoobjectsareconnected. Relationshipsaredescribedusingtwoormoreobjectsandsomemetadata.Theyareclassifiedas: o Lightweightrelationshipswhichhavenoinheritance;theobjectstowhichtheyreferdonot influencetheunderlyingnatureoftheobjectonwhichtherelationshipexists.Theserelationships areusedprimarilywhenmovingaroundtheobjecttreeandconnectingobjecttreestoeachother. ThelightweightrelationshipsareIsPackagingOf,IsPromotionFor,IsAdjunctTo,and IsAlternateContentFor. Dependencerelationshipswheretheobjectstowhichtherelationshiprefershaveastrong bearingonthebasicnatureoftheobjectonwhichtherelationshipexists.Importantly,thismeans thattheobjectsreferredtointherelationshipneedtobetakenintoaccountwhencheckingfor duplicateswhenanobjectiscreatedormodified.ThedependencerelationshipsareIsCompositeOf andIsEncodingOf. Inheritancerelationshipswheretheobjectonwhichtherelationshipexistscaninheritbasic metadatafieldsfromtheobjecttowhichtherelationshiprefers.Withtheexceptionis IsLanguageVariantOf,onlyoneinheritancerelationshipmayexistonanobject.TheInheritance relationshipsareIsSeasonOf,IsEpisodeOf,IsEditOf,IsLanguageVariantOf,IsEncdoingOf,andIsClipOf.
EIDRAPIOverview
P a g e |9
Version1.0120110407
Creation of Objects
BasicObjects withIsSeasonOfinheritance relationship withinformationforderived typeInteractiveMaterial withinformationforderived typeSeries withIsEncodingOfinheritance relationship withIsEditOfinheritance relationship withIsClipOfinheritance relationship withIsLanguageVariantOf inheritancerelationship withIsEpisodeOfinheritance relationship withIsCompositeOf dependentrelationship Referenttypecanbe:TVShow, Movie,Short,Web OnlywaytocreateSeasonreferent type Onlywaytocreate InteractiveMaterialreferenttype OnlywaytocreateSeriesreferent type
Creation Type
Onlywaytocreateanobjectthathas CreateEncoding IsEncodingOfrelationship Onlywaytocreateanobjectthathas CreateEdit IsEditOfrelationship Onlywaytocreateanobjectthathas CreateClip IsClipOfrelationship Createsachildwitha IsLanguageVariantOfrelationship CreateLanguageVariant
Type
Inheritance Inheritance Inheritance Inheritance
Removable?
No No No No
EIDRAPIOverview
P a g e |10
Version1.0120110407
Relationship
IsCompositeOf
Type
Dependence
Removable?
Yes,ifthereferenttypeisnot Composite
IsEncodingOf
IsLanguageVariant
No
No
IsLanguageVariant
Yes,provided someother inheritance relationship alreadyexistson theobject;both relationships musthavethe sameParent Yes
IsPromotion
Lightweight
Any
IsPackaging
Lightweight
Any
Yes
IsAlternateContent
Lightweight
Any
Yes
IsAdjunctContent
Lightweight
Any
Yes
ThelightweightrelationshipsIsPromotion,IsPackaging,IsAlternateContent,andIsAdjuctContentcanbe addedtoanyobjectatanytime. Anyrelationshipthatcanbeaddedcanberemoved,withthefollowingexceptions: IsLanguageOfisnotremovableifitistheobject'sonlyinheritancerelationship.Thisisthecase whenthelanguagevariantwassuppliedatcreationtime. IsCompositeOfisnotremovableiftheobject'sreferenttypeisComposite.Thiswillbethecase whenthecompositeinformationwassuppliedatlanguagecreationtime. Seetheappendixforexamplesofmodifyingobjects. 3.1.3. CREATE Create(creationType, creationData, mode) Returnsastatustoken,foruseinGetStatus()calls.Objectsthatarecreatedwithastatusof InDevarenotcheckedbythededuplicationservice;theyaresentfordeduplicationwhenthey arepromotedtoValid.(SeethePromote()call.) Modeisoftypeeidr:requestModeTypeandcanbeeitherasynchronousorimmediate. IntheRESTimplementation,thisispassedinthehttpheadersratherthanintheXMLforthe request. Batchinputallowed. ThereisadatatypedefinedintheschemaforeachcreationType,andthetwomustmatchin thecall.Forexample,tocreateaseriesyouwoulduseCreateSeriesand CreateSeriesData.ThesetypesaresubsetsofFullObjectInfoTypeandareusedtolimit thescopeformistakesforcommonoperations. Errors:Standarderrors;alsoseeGetStatus() 3.1.4. ADDINGANDREMOVINGRELATIONSHIP Adding,removing,andreplacingrelationshipsislimitedtothoserelationshipsthatarenotdeterminantsof theobject'snature.Forexample,youcan'taddIsSeasonOf,orremoveIsEpisodeOf. AddRelationship(DOI, relationshipType, relationshipData) Returns:astatustoken,foruseinGetStatus()calls.AValidationErrorisreturned(viathe status)iftherelationshipcannotbelegallyaddedtotheobject. relationshipTypeandrelationshipDataareoneofthefollowingpairs: CompositeRelationship, compositeInfoType LanguageRelationship, languageConstructionInfoType P a g e |12 Version1.0120110407
EIDRAPIOverview
RemoveRelationship(DOI, relationshipType) Returns:astatustoken,foruseinGetStatus()calls.ANotRemovable errorisreturned(via thestatus)iftherelationshipcannotbelegallyremovedfromtheobject. LegaltypesareasforAddRelationship(). Allrelationshipsofthespecifiedtypeareremoved.(Onlylightweightrelationshipscanexistmultiply onanobject,however.) IsCompositeOfisonlyremovableiftheobject'sreferenttypeisnotComposite. Errors:standarderrors RemoveSpecificRelationship(DOI, relationshipType, targetDOI) Returns:astatustoken,foruseinGetStatus()calls.ANotRemovable errorisreturned(via thestatus)iftherelationshipcannotbelegallyaddedtotheobject. relationshipTypemustbeoneofthelightweightrelationships.Ifthereisarelationshipof thattypewithtargetDOI,itisremoved. Errors:standarderrors ReplaceRelationship(DOI, relationshipType, relationshipTypeData) Returns:astatustoken,foruseinGetStatus()calls. relationshipTypeandrelationshipDataareoneofthefollowingpairs: CompositeRelationship, compositeInfoType LanguageRelationship, languageConstructionInfoType
TheexistingrelationshipinformationforrelationshipTypeontheobjectisreplacedbythe newrelationshipTypeData. IfthereplacedrelationshipisLanguageRelationship,theParentfieldofanyother inheritancerelationshipontheobjectisreplacedwiththeParentfieldof relationshipTypeData. Errors:standarderrors 3.1.5. MODIFYINGOBJECTS Modifyingobjectsisdonebygettingcurrentinformationontheobject,modifyingit,andresubmittingit. GetModificationBase(DOI, creationType) ReturnsobjectmetadataforcreationType.Theschemasusedforthereturnarethesameas theoneusedforcreatinganobjectofthattype. Forexample,consideranobjectcreatedusingCreateSeries. GetModificationBase(DOI, CreateBasic)returnsjustthefieldonthebasicobject,and GetModificationBase(DOI, CreateSeries)returnsallthemetadataneededtocreatea series. TheunderlyingobjectmustbeabletosupportallthefieldsneededbycreationType.Itisincorrect tocallGetModificationBase(DOI, CreateComposite)ontheobjectintheprevious example. Errors:standarderrorsandIncompatibleCreationTypes. Modify(DOI, creationType, creationTypeData) Returns:astatustoken,foruseinGetStatus()calls.Therequestispassedtothededuplication systeminthesamewayasaregularCreate()call 2 .Itispossible,thoughnotnecessarilysafe,to passindatanotreturnedfromGetModificationBase().Iftheobjecthasmultipleinheritance relationshipsandParentischangedincreationTypeData,theParentfieldoftheother inheritancerelationshipsischangedaswell. Batchinputallowed. Errors:standarderrorsandIncompatibleCreationTypes. 3.1.6. PROMOTE ThiscallturnsanInDevobjecttoaValidobject.Onceitismade,thereferencedobjectisvisibletothe worldatlarge.
Note that children of the modified object are not passed to de-duplication, even though they might inherit the changed values.
EIDRAPIOverview
P a g e |14
Version1.0120110407
InDevobjectsdonotgothroughthededuplicationsystemwhentheyarecreated,butarecheckedfor duplicateswhenpromoted.ThereturnedtokencanbeusedinGetStatus()calls. Promote(DOI, mode) Returns:statustoken. Modeisoftypeeidr:requestModeTypeandcanbeeitherasynchronousorimmediate. IntheRESTimplementation,thisispassedinthehttpheadersratherthanintheXMLforthe request. Batchinputallowed. InDevobjectsdonotgothroughthededuplicationsystem,butarecheckedforduplicateswhen promoted.ThereturnedtokencanbeusedinGetStatus()calls. Ifthecallissuccessful,thePromoteandViewACLsareremovedfromtheobject,anditis viewablebyanyuser. ReturnsstandarderrorsandNotInDev. 3.1.7. DELETE Ideally,everyDOIispermanent.Sometimes,however,anitemreallydoesneedtobedeleted(forexample, acancelledprojectatadefunctproductionhouse),orissobadlywrongitshouldberemoved. EIDRdoesnotdeletetheDOIitself;rather,itmakestheDOIanalias(seebelow)forastandardtombstone object. Delete(DOI) ReturnsstatustokenforuseinGetStatus() ForcestheDOItoresolvetoatombstone. TheLastModifiedfieldintheprovenanceforadeletedDOIisthetimeatwhichtheobjectwas deleted. Onlyanobjectwithnorelationshipsandnodependentscanbedeleted.Use FindDescendents()andGetLightweightRelationships()(orresolveto eidr:simpleDataInfoType)tofindtherelationshipsandGet Dependents()for dependentitems. Batchinputallowed Errors:standarderrorset,anddependencyerrors 3.1.8. ALIAS AnaliasisasimpleindirectionfromoneDOItoanother.Analiasisnotintendedasageneraltool;rather,it shouldonlybeusedforcorrectingerrors.Forexample,ifafilmmistakenlygetstwoIDs(perhapsbecauseof problemsinvolvingworkflowandworkingtitles)theincorrectonecanbealiasedtothecorrectone.Asa concreteexample,ifawrongIDgetsburnedontoaBDlivediskandissubsequentlycorrectedbyaliasing, EIDRAPIOverview P a g e |15 Version1.0120110407
ConvertToAlias(OldIdentity, NewIdentity) SubsequentreadsofOldIdentityreturndatafromNewIdentity.Anyotheraction(suchas atraversalorarootedquery)requestedonOldIdentitywillgenerateanerror. OldIdentityremainsavalidIDinthesystem,anditisstillresolvable. Afterthiscall: Readingdata o o o o AllresolutionsrelatedtoOldIdentitywillreturndatafromNewIdentity, unlessthecallhasafollowAliasflagsettofalse. Allothercallsreturnanerror;theapplicationshouldfollowthealiastogetthe actualDOI,andthenuseit. TheLastModifiedfieldintheprovenanceforanaliasedDOIisthetimeatwhich theobjectwasaliased. Applicationhint:iftheDOIinthemetadatafromaresolutionisnotthesameasthe inputDOI,theinputDOIhasbeenaliased.
Queries:AllqueriesrelativetothealiasedDOIwillreturnanerror.
Onlyanobjectwithnorelationshipsandnodependentscanbealiased.Use FindDescendents()andGetLightweightRelationships()(orresolveto simpleDataInfoType)tofindtherelationshipsandGet Dependents()fordependent items. Errors:standarderrorset,HasDependents,andIncompatibleAliasTarget 3.1.9. REQUESTSTATUS Allasynchronouscallsreturnatokenthatcanbeusedtoquerythestatusoftherequest. GetStatus(token, page, pageSize, continuationToken) Errors:standarderrors,BadQuery,andResultTooLong Thepagingparametersareusedasfollows:
EIDRAPIOverview
P a g e |16
Version1.0120110407
Returns(token, status)elementiftoken isnotabatchtoken. Iftoken isabatchtoken,returns PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults ContinuationTokenreturnedbyimplementationsthatinternallycacherequeststate. ItshouldbepassedinastheContinuationTokenargumentonsubsequentcallsasan accelerator.
Alistofthe(token, status)elementforeachiteminthebatchthatfallsinthe returnedpageofresults Valuesforatokenrepresentingabatch BatchReceivedthebatchhasbeenfullyreadin,butnostatusforitssub elementsisavailable BatchQueuedthebatchisbeingprocessed,andstatusisavailableforallitssub elements BatchInvalidtherewasanerrorinthebatch;oneofthestandarderrorsis alsoreturnedasadetail
Valuesfortokensforindividualitemsinthebatch: Success:Whentherequesthassucceeded,forexamplebycreatinganewobject ordeletinganoldone.ThedetailfieldcontainstheDOIassociatedwiththe successfuloperation:anewDOIforcreation,andthepassedinDOIinothercases. Duplicate:Whenaduplicateorpotentialduplicatesarefoundduringcreate, modify,orpromote.ThedetailfieldcontainsoneormoreDOIsofitemsdetectedas duplicates;theIDsforallduplicatesarereturned. Pending:Whentheregistryiswaitingtofinishanoperation,buthasnotyethad anyerrors;inthecaseofcreate,modify,andpromoteitmayhaveasadetailalist ofDOIsforoneormorepotentialduplicates.
EIDRAPIOverview
P a g e |17
Version1.0120110407
ThecallitselfcanreturnanyofthestandarderrorsoraBadToken error. GetStatus(Registrant, filter, token, page, pageSize, continuationToken) GetStatus(User, filter, token, page, pageSize, continuationToken) ThelastfourargumentsaretreatedastheyareforGetStatus(). Filtercanbe: Status: legal-status-value:Onlytokensthatmatchthesuppliedvalueare returned. After: date-time:Onlytokensissuedafterthesuppliedtimearereturned. Range: date-time-start date-time-end:Onlytokensgeneratedbetweenthe twodatesarereturned.
Registrantreturnsapaginatedlistof(token, status)foreverytokenbelongingto RegistrantthatmatchesFilter.AtokenbelongstoaregistrantifauserinRegistrants groupmaderequestwithwhichitisassociated. Userreturnsapaginatedlistof(token, status)foreverytokengeneratedbyarequestfrom UserandmatchingFilter. 3.2 OBJECTINFORMATION ThereareseveralwaysofgettinginformationaboutaDOI: ResolutionprovidesvariousviewsofthemetadataassociatedwithaparticularDOI. TraversalprovidesinformationabouthowtheDOIfitsintotheobjecthierarchy.
EIDRAPIOverview
P a g e |18
Version1.0120110407
3.2.1. RESOLUTION Resolve(DOI, resolutionType, followAlias) Returns:metadataassociatedwiththeDOI. IffollowAliasistrue(thedefault),informationreturnedisfromtheobjecttowhich analiasedrefers,notfromthealiasedobjectitself. IffollowAliasisfalseandtheobjectisnotaliased,theinformationlikewisecomes fromtheobjectitself. IffollowAliasisfalseandtheobjectisaliased,anAliasContinuationis returned. Notes: Analiascanbedetectedasfollows: o WhenfollowAliasistrue,bycomparingtheDOIfieldofthereturnedobjectwiththe inputDOI;iftheydiffer,theinputDOIisaliased. WhenfollowAliasisfalse,bydetectingthatanAliasContinuationhasbeen returnedratherthanformattedmetadata. Aliasesarefollowedforfivelevels.Ifthefinalitemisstillaliased,an AliasContinuationobjectisreturnedwhichcontainsthelastaliasedDOIfoundand theitemtowhichitisaliased.
ForresolutionType,thedefinedvaluesandbehaviorareasfollows: ResolutionType
DOIKernel
Follow Alias?
true
Return Value
Returnsmetadataformattedasdoi:kernelMetadata. Ifthealiaschainistoodeep,returnsan AliasContinuation. ForanInDevobject,returnsastructuraltypeofrestricted.The object'snameis"No information available". Foradeletedobject,returnsastructuraltypeof'Restricted',and fieldvaluesfromthestandardtombstoneobject.
EIDRAPIOverview
P a g e |19
Version1.0120110407
ResolutionType
DOIKernel
Follow Alias?
false
Return Value
Iftheobjectisaliasedthisreturnsdoi:kernelMetadata where: structural type is 'Restricted' title is 'aliased' referentCreation.identifier.typeisDOI referentCreation.identifier.value is the DOI to which the object is aliased
Foradeletedobject,returnsastructuraltypeof'Restricted',and fieldvaluesfromthestandardtombstoneobject. Simple true Returnsmetadataformattedaseidr:simpleDataInfoType. Thisistheformatreturnedbyqueriesandtraversals. Ifthealiaschainistoodeep,returnsanAliasContinuation. Simple false Iftheobjectisnotaliased,returns eidr:simpleDataInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.) Full true Returnsmetadataformattedaseidr:fullObjectInfoType. Ifthealiaschainistoodeep,returnsanAliasContinuation. Full false Iftheobjectisnotdeletedoraliased,returns eidr:fullObjectInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.) SelfDefined true Returnsmetadataformattedas eidr:allSelfDefinedInfoType. Ifthealiaschainistoodeep,returnsanAliasContinuation. SelfDefined false Iftheobjectisnotdeletedoraliased,returns eidr:allSelfDefinedInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.) Inherited true Returnsmetadataformattedas eidr:allInheritedInfoType. Ifthealiaschainistoodeep,returnsanAliasContinuation. Inherited false Iftheobjectisnotdeletedoraliased,returns eidr:allInheritedInfoType. Iftheobjectisaliased,returnsAliasContinuation.(See above.).
EIDRAPIOverview
P a g e |20
Version1.0120110407
ResolutionType
Provenance
Follow Alias?
true
Return Value
Theprovenancerecordforobject(withthealiaschainfollowed)as eidr:provenanceInfoType. Ifthealiaschainismorethan5deep,returnsan AliasContinuationobject.
Provenance
false
SeetheAppendixfordetailsonthecomplexinheritancetypes(forResourceNameand languages.) 3.2.2. TRAVERSAL TraversalsareusedfordiscoveringhowtheDOIfitsintothegraphthatrepresentsitsrelationshiptoother objects. Traversalsstopatthefirstobjectforwhichtherequesterdoesnothavereadpermission.Thestandard PermissionerrorisusedonlyforpermissionerrorsontheDOIintheoriginalrequest. Traversalsalwaysfollowaliases. Alltraversalsreturnresultsindepthfirstorder. FindAncestors(DOI, list of referentTypes, list of structuralTypes, list of relationshipTypes) Returnsalistof(simpleData, generationsAbove)forallancestorswhichmatchoneofthe referenttypes,oneofthestructuraltypes,andoneoftherelationshiptypes.Emptylistsmatch anything.Thesearchstopswhenanobjecthasnoancestors,andonlyancestorsthatcountfor inheritanceareconsidered(i.e.,noneofthelightweightrelationshipscount). generationsAboveis1foraparent,2fortheparent'sparent,etc. Theobjectitselfisnotreturned. Recallthatobjectscanonlyinheritfromoneparent. Examples: FindAncestors(DOI, "", "", "")findsalloftheobject'sancestors. FindAncestors(DOI, "", "", "IsEditOf")findsallancestorsthatareeditsofa predecessor.
FindDescendants(DOI, list referentTypes, list of structuralTypes, list of relationshipTypes) EIDRAPIOverview P a g e |21 Version1.0120110407
Returnsalistof(simpleData, generations above)foralldescendantswhichmatchoneof thereferenttypes,oneofthestructuraltypes,andoneoftherelationshiptypes.Emptylistsmatch anything.Thesearchstopswhenanobjecthasnodescendants,andonlyitemsthatcaninherit considered(i.e.,noneofthelightweightrelationshipscount). generationsBelow is1forachild,2forachild'schild,etc. Theobjectitselfisnotreturned. Recallthatobjectscanonlyinheritfromoneparent. Examples: FindDescendants(DOI, "")findsalltheDOIsdescendants. FindDescendants(DOI, "digital","","IsEncoding")findsalltheencodings descendedfromtheDOI. FindDescendents(DOI, "","season")findsalltheseasonsdescendedfromDOI. GetDependentObjects(DOI) Returnsalistofeidr:simpleDataInfoTypeforDOIsthatdependontheinputDOIthatare notpartofaninheritancerelationshiporalightweightrelationship. ThiscanbeusedtofindcompositesandencodingsthatincludeaparticularDOI. Theremainingtraversalfunctionsareprovidedasaconvenience;theycanallbeimplementedattheclient byparsingtheresultsofresolutionsandtheabovetraversals. GetSeriesAncestry(DOI) Returnseidr:seriesAncestryType,whichis: eidr:simpleDataInfoTypefortheDOI eidr:simpleDataInfoType and eidr:episodeInfoTypeforthenearest ancestor(whichcanbetheinputDOI)thathasepisodedataonit.Notpresentifthereisno suchancestor. eidr:simpleDataInfoType and eidr:seasonInfoTypeforthenearest ancestor(whichcanbetheinputDOI)thathasseasondataonit.Notpresentifthereisno suchancestor. eidr:simpleDataInfoType and eidr:seriesInfoTypeforthenearest ancestor(whichcanbetheinputDOI)thathasseriesdataonit.Notpresentifthereisno suchancestor. P a g e |22 Version1.0120110407
EIDRAPIOverview
Thevalidationrulesenforcethattherecanbenomorethanoneancestorofeachofthetypes. ThisfunctionisintendedforusebyUIs,managementreports,andsoon. GetLightweightRelationships(DOI) ReturnsthelistofDOIstowhichtheinputDOIhasanoninheriting(i.e.'lightweight')relationship. Eachelementinthelistcontains: eidr:simpleDataInfoType fortherelatedDOI thetypeoftherelationship(IsAdjunct,etc.) theclassoftherelationship(e.g.,Outtake) GetRemotestAncestor(DOI) Returnseidr:simpleDataInfoTypeandgenerationsAboveforthemostdistant ancestor. Iftheinputobjecthasnoancestors,theinputobjectisreturned. Iftheobjecthasancestors,thisistheequivalentoflookingforthehighestnumbered generationsAboveinthereturnvaluesfromFindAncestors(DOI, "", "", ""). GetLeafDescendants(DOI) Returnseidr:simpleDataInfoTypeandgenerationsBelowforalldescendantsthathave nodescendantsoftheirown.NotethatgenerationsBelow maynotbethesameforallleaf nodes. Iftheinputobjecthasnodescendants,theinputobjectitselfisreturned. Iftheobjecthasdescendants,Thiscanalsobedonebyinterpretingtheresultsfrom GetDescendants(DOI, "", "", ""),butthatisalittletrickysincenotallleaf descendantswillbeatthesamelevel;youreallydohavetobuildasimpletreefromthereturned values. GetParent(DOI) Returnseidr:simpleDataInfoTypefortheinputDOI'sparent. ReturnsanerrorofNoParentiftheinputobjectisatthetopofatree. ThisisusefulifallyouhaveisaDOI,notanyofitsmetadata,andwanttoknowitsparent.Itcanbe doneanywaybylookingforgenerationsAbove=1intheresultsofGetAncestors(DOI, "", "", ""). GetChildren(DOI)
EIDRAPIOverview
P a g e |23
Version1.0120110407
Returnseidr:simpleDataInfoType foralloftheinputDOI'simmediatedescendants. ReturnsanerrorofNoChildreniftheinputobjectisaleafofatree. ThiscanbeimplementedbylookingforgenerationsBelow=1intheresultsof GetAncestors(DOI, "", "", ""). 3.2.3. QUERIES OVERVIEW Thequeryfacilitytakesasetofmetadatacriteriaasinputandreturnseidr:simpleDataInfoTypefor allobjectsthatmatchthosecriteria.Thesimplestquerytestsasinglemetadatafield.Morecomplex queriescanbebuiltupbygroupingsimplequeriestogetherwithstandardlogicalexpressions. ThemetadatafieldstobetestedarerepresentedwithasubsetofXPathnotationthatsupportsonly completepathstoelementsandattributes.TheXPathusedinqueryrequestscanbebasedon: Intheseexamplestheparenthesesarenotstrictlynecessary,butimprovelegibility.NotethatXMLatthe protocollevelrequiresescapingofspecialcharacters(<,>,etc.),althoughproceduralimplementationsof theAPImayhidethatfromtheapplication. Thisqueryfindsallobjectslongerthan20minutesandshorterthan40minutes:
(/FullMetadata/BaseObjectData/ApproximateLength > PT20M00S) AND (/FullMetadata/BaseObjectData/ApproximateLength < PT40M00S)
Thisfindsallrecordsmodifiedin2010.(Seebelowfortheprecisionofdatecomparisons.)
(/ProvenanceMetadata/LastModificationDate = 2010)
EIDRAPIOverview
o o
esmatchesobjectsthathavees,esES,andes419 deCHmatchesdeCH,butnotdeordeDE.
Forexample,thisfindsallobjectsthathaveinformationaboutseparatelyencodedsubtitles:
(/FullMetadata/ExtraObjectMetadata/EncodingInfo/SubtitleInfoBlock EXISTS)
TextMatching: Textqueriesarecaseinsensitive. Boththetextinthequerystringandthetextstoredintheregistryaregenerallyprocessedinto tokensbeforematching.Tokenizationconsistsofoneormoreofthefollowingsteps. o Normalization:Sequencesofwhitespacearecollapsedintoasinglespace;somepunctuationis convertedtospaces;andsomepunctuationisremoved(causingconcatenationofthestring beforeitwiththestringafterit).Thisgivesaseriesoftokens. Twofilterscanbeappliedtothetokensthatresultfromnormalization: o Stopwords(small,commonwords,suchas'the'or'in'inEnglishor'la'and'en'in Spanish)arefiltered. o Wordsarestemmed;stemmingremovesplurals,turnsinflectedwordsintothe appropriateroot,andsoon.
PleaseseetheTextProcessingAppendixforlanguagedependenciesanddetailsofwhichoftherulesare appliedtoeachmetadatafield. Therearetwokindsoftextqueries: Theform<field> <string1><stringN>istrueforanyfieldthathasoneormoreofthe strings.Itisequivalentto<field> <string1> OR <field> <string2> OR ... OR
<field> <stringN> Theform<field> "<string>"istrueforanyfieldthathasexactly<string>init.<string>
EIDRAPIOverview
P a g e |25
Version1.0120110407
Thegrammarforqueryexpressionsis: 3
<expression> ::= | | | <term> ::= | | | <term> <expression> OR <term> <expression> AND <term> NOT <term> <field> <field> <field> <field>
EXISTS
<string> <string>* "<string>" IS "<string>"
| <field> ISNOT "<string>" | <field> <logop> <value> | ( <expression> ) <field> ::= legal xpath attribute | legal xpath element ::= number | date | time | duration ::= = | <> | < | <= | > | >=
<value> <logop>
Willmatchrecordswhoseprimarylanguageisen,butnoten-US,sinceen-USisretainedasthe singletokenen-US,notthetwotokensequenceen US. Althoughrangesarenotdirectlysupported,theycanbeimplementedusingtwosimplequeries combinedbyAND. Fieldsthatcontaincontrolledvocabularyaretokenized,withpunctuationcharactersremoved. Theemptystringmatchesnothing,ratherthaneverything. Fornonexistentfields,allISNOTcomparisonsevalauateasTrue.Forexample,ifthereisno CountryOfOriginfield,(/FullMetadata/BaseObjectData/CountryOfOrigin ISNOT fr)is True. ISandISNOTapplytoValue,Valuelanguage,andTextfields.
NOTE: * is the equivalent of EBNF {} and "<term> || NOT <term>" could be EBNF "[NOT]<term>"
EIDRAPIOverview
P a g e |26
Version1.0120110407
o o
Comparisonsaredonetotheprecisionoftheleastpreciseargument.Forexample,adatefield containing2010is>=,<=,and=to10102010.Comparingadateof2010to10isnot<>,<,or>10 102010 Someapplicationsmaywanttodoqueriesacrossonlymetadataontheobjectitself,asopposedto thefullmetadata.Thiscanbeusefulforapplicationswhosemainpurposeisdealingwiththe metadata,ratherthandealingwiththeobjectsdefinedbythemetadata.Thiscanbedonebydoing aregularquery,callingResolve()toreturnonlyselfdefinedmetadata,andthenexamining thoseresults. Asanexample,imagineaRegistrythathasobjectswiththefollowingtitlesintheResourceName fields: o o o o o o o o o o Batman:TheDarkKnight KnightofDarkStories DancingInTheDark DarknessAtNoon DarknessWaits TheGhostandTheDarkness ShanghaiKnights ShanghaiNoon Sinbad:TheBattleoftheDarkKnights FirstKnight
Results
Batman:TheDarkKnight KnightofDarkStories DancingInTheDark Sinbad:TheBattleoftheDarkKnights
Notes
Anythingwith'Dark'
Batman:TheDarkKnight
EIDRAPIOverview
P a g e |27
Version1.0120110407
Expression
field Dark Knight
Results
Batman:TheDarkKnight KnightofDarkStories DancingInTheDark Sinbad:TheBattleoftheDarkKnights FirstKnight
Notes
Anytitlethathas'Dark'or 'Knight'.
field Knights
ShanghaiKnights Sinbad:TheBattleoftheDarkKnights
Anytitlewith'Knights'
(field Dark) AND (field Knight) (field Dark) AND NOT (field The)
willbemoreresponsivethan
API RootedQuery(DOI, queryExpression, page, pageSize, continuationToken) GeneralQuery(queryExpression, page, pageSize, continuationToken) Returnstypeeidr:queryResults,whichcontains: PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults
EIDRAPIOverview
P a g e |28
Version1.0120110407
TheonlydifferencebetweenthetwoqueryfunctionsisthatRootedQuery()onlyreturnsresults thatarethechildrenoftheDOIargument. Theresultsaresortedbylanguagecodeoftheprimarytitle,andthenbytitlewithineachlanguage code. Errors:standarderrors,BadQuery, ResultTooLong 3.2.4. VIRTUALFIELDS Besidesindividualfields,anobjectcontainstwo'virtual'stringfieldsthatcombinemultipleotherfields. Bothofthesearenormalized(punctuationstripped,spacescollapsed)andtokenizedusingthedefault (English)rules.Stopwordfilteringandstemmingarenotapplied. 4 Thisalsoappliestostringsasquerieson thevirtualfields. FullStringcomposedofthesefieldsfromFullObjectMetadataType o o o o o o BaseObjectData/ResourceName BaseObjectData/AlternateResourceName BaseObjectData/DisplayName BaseObjectData/Description BaseObjectData/Credits/Director/DisplayName BaseObjectData/Credits/Actor/DisplayName(usingallthatarepresent)
Many of the components of the virtual field are names and titles, which are not filtered or stemmed on their own, and this rule applies to the whole virtual field.
4
EIDRAPIOverview
P a g e |29
Version1.0120110407
SelfDefinedStringasFullString,butonlythosefieldsthatarenotinherited Inqueries,thevirtualfieldsare /VirtualField/Full /VirtualField/SelfDefined Theorderofthetokenswithineachoftheconstituentfieldsispreserved,buttheorderinwhichthe constituentfieldsareaddedtothevirtualfieldisnotdefined.Thismeansthatanexactmatchquery(using <field> "<string">)returnsunpredictableresultswhentheexactquerymightmatchtoken sequencesthatcrossfields.Itmatchestokensequenceswithinindividualfieldspredictablyasitwouldon thesinglefield. ThevaluesofthevirtualfieldscanberetrievedusingGetVirtualFields().Thiscanbeusefulfor debugging,butisnotintendedtobeusedforpresentationtoanenduser. GetVirtualFields(DOI) Returnsastructureoftypeeidr:VirtualFieldscontainingthetwostrings Errors:standarderrorsonly 3.2.5. PROVENANCE Anobject'sprovenanceinformationcanberetrievedbycallingResolve(DOI, "Provenance", followAlias. Whenanobjectiscreated,itsLastModificationDateissetequaltoitsCreationDate. TimesintheprovenancearestoredasUTCwiththeexplicittimezonemarkerZ.
4. PARTIES,USERS,ANDPERMISSIONS
APartyrepresentsanentitysuchasaregistrantoraproducingagent.AUserisanindividual(oranabstract thingthatcanbetreatedasanindividual.)Note:forhistoricalreasons,theinitialimplementation sometimescallsaPartya'Group.' AllUsersareassociatedwithaParty.Thecurrentversionoftheregistrysupportsonlythissinglelevelof hierarchy;futureversionsmayaddsubentities,aswell,forrepresentingdifferentorganizationwithina singleEntity. Allrequeststotheregistrycontainauthenticationinformationforapartyandauser. TheUserrequestingthecreationofanewobjectmustbeassociatedwiththeRegistrant(aParty)givenin theregistrationdata. OnlyPartieshavepermissionsinthesystem;aUserhasallthepermissionsassociatedwithitsparentParty. Note:OnlytheRegistrationAuthorityhastheabilitytocreateormodifyparties. EIDRAPIOverview P a g e |30 Version1.0120110407
4.1 PARTIES ThereisapredefinedPartyrepresentingtheRegistrationAuthority. Anentitycanbeoneormoreofthefollowing: ProducingAgent:Thesebringforththeobjectbeingregistered:astudiointhecaseofan abstractwork;oranencodinghousefortheworkinafinaldigitalform;orevenanantipiracy vendorforregisteringanewillegalcopyofawork.Theimportantthingtorememberaboutthis fieldisthatitreferstotheentitythatmostrecentlytouchedtheitem. Registrants,whoregisteritems.Aregistrantmaybeaprincipalagent,suchasastudiooran encodinghouse,oritmaybeanexternalentitydoingbulkregistrationofbackcatalogueitems. CurrentAssetHolder:Thispartymaybeincludedoptionallybytheregistranttoindicatethe entitytheregistrantthinksismostlikelytohavesomeauthorityoverthisobject.Forexample,a metadataproviderdoingbulkregistrationmaymakethisfieldthesameastheProducingAgent forobjectsreasonablysuretobeunderthecontrolofthatentity,andleaveitblankotherwise. BackupContact:Optionallyregisteredentitiesthatmaybeabletosortoutthingsthatare otherwisebeyondthekenoftheRegistrant. EncodingVersionAgent:optionalentityusedwhenregisteringencodings.
Asanexample,anencodinghousethatregistersnewencodingswillbetheRegistrantfortheobject.Inthe strictestsense,theycouldbetheProducingAgentaswell,butthatisnotmandated;forexample,therights holdercouldrequirethattheProducingAgentfortheencodingbethesameasthatfortheparentobject. TheencodinghousewillalsoprobablybetheEncodingAgentforeachitem,unlesssomeaspecthasbeen subcontractedoutelsewhere(e.g.,toaspecialistsubtitleshop.) APartycanbeeitherActiveorInactive.AninactivePartymaynotmakeanymodificationstothedatabase; thatis,itmaynotbeaRegistrantoraWriter,andallUsersassociatedwithitaresimilarlyrestricted. 4.1.1. CREATE CreateParty(partyData) ReturnsaDOIoftypeeidr:partyDOITypeforthenewlycreatedparty.Theparameter partyDataisoftypeeidr:partyCreationType. ThesuffixofthereturnedDOIisthePartyAccountNamefieldfrompartyData.Itmustnot matchanyotherPartyAccountNameinthesystem. Errors:StandarderrorsorDuplicateParty.
EIDRAPIOverview
P a g e |31
Version1.0120110407
Note:IntheinitialversionoftheRegistry,onlyminimalcheckingisdoneforduplicatesofParties. ApplicationsusingCreateParty()shouldbeaccordinglycautious. CreateUser(userData) ReturnsaDOIoftypeeidr:userDOITypeforthenewlycreateduser. userDataisoftypeeidr:userCreationType,withthefollowingconstraints: userData.Usernameisoftypeeidr:usernameType andmustnotmatchanyother usernameinthesystem. userData.ParentPartyisoftypeeidr:partyDOIType userData.Passwordmustbe632characterslong
ThesuffixofthereturnedDOIistheUsernamefieldfromuserData. Errors:Standarderrors,DuplicateUser, or BadParty. Note:TheinitialversionoftheRegistryonlychecksforanexactduplicateofusername. 4.1.2. MODIFY ModifyParty(partyData) Returnssuccessoranerror. partyDataisoftypeeidr:partyResolutionType.ResolveParty(partyID, "full") returnsanappropriatebaseformodifications. Notethatthisdoesnotincludethepasswordfield.partyData.IDcannotbemodified. Errors:StandarderrorsorBadParty. ChangePartyPassword(partyID, newPartyPassword) ChangestheParty'spassword.Theoldpasswordisnotsentseparately;itisalreadywiththe credentialsentwiththecall. Errors:StandarderrorsorBadParty. ModifyUser(userInfo) Returnssuccessoranerror. userInfo isoftype eidr:userResolutionType. ResolveUser(userID, "full") returnsanappropriatebaseformodifications. Notethatthisdoesnotincludethepasswordfield.userInfo.IDcannotbemodified. Errors:Standarderrorsor BadUser. ChangeUserPassword(userID, newUserPassword) ChangestheUser'spassword.Theoldpasswordisnotsentseparately;itisalreadywiththe credentialsentwiththecall. EIDRAPIOverview P a g e |32 Version1.0120110407
4.1.3. ADMINISTRATIVETASKS Note:OnlytheRegistrationAuthoritycanperformthefollowingtasks. DeactivateParty(partyID) ReturnsSuccess,StandardErrorsorBadParty. Ifsuccessful,usersassociatedwiththepartyarenolongerallowedtodoanythingthatrequires presenceonanACL.partyIDisvirtuallyremovedfromACLs(theRegistrychecksthe active/inactivestateofentriesintheACL),notactuallyremoved;thisallowseasydeactivationand reactivationofpartiesforadministrativereasons. ActivateParty(partyID) ReturnsSuccess,StandardErrorsorBadParty.Ifsuccessful,thePartyismadeactive. DeactivateUser(userID) ReturnsSuccess,StandardErrorsorBadUser. Ifsuccessful,theuserisnolongerallowedtodoanything;authenticationoftheuser'scredentials willfail. ActivateUser(userID) ReturnsSuccess,StandardErrorsorBadUser. Ifsuccessful,theuser'scredentialsarevalidandauthenticationofthemsucceeds. ValidateCredentials(partyID, userID, password) partyID isoftypeeidr:partyDOITYpe userID isoftypeeidr:userDOIType password isoftypeeidr:simplePasswordType. Returns: 'allvalid'iftheuserIDandpasswordarecorrectanduserIDisassociatedwithpartyID. 'wrongparty'iftheuserandpasswordmatchbutuserIDisnotassociatedwithpartyID 'invalid'istheuserandpassworddontmatch.
Returnsmetadatafortheparty;theformatoftheresultisdependentonthetypeparameter. Type
DOIKernel Full
Format
DOIkernelmetadataforaParty eidr:partyResolutionType;seetheschema. The PartyAccountNamefieldwillmatchthesuffixoftheDOI
Format
DOIkernelmetadataforaCreation,withstructuraltypeofrestricted.Theobject's nameis"No information available". eidr:userResolutionType;seetheschema. TheUsernamefieldwillmatchthesuffixoftheDOI.
Full
Errors:Standarderrors,orBadUser GetUsers(partyID) Returnslistofeidr:userDOITypeforallUsersassociatedwithpartyID,whichmustbeof typeeidr:partyDOIType. Errors:Standarderrors. FindPartiesByName(string, roleFilter, activeFilter, page, pageSize, continuationToken) Seebelowforuseofpagingparametersandstring. roleFilterisanoptionallistofstringsoftypeeidr:administratorTypeType. activeFilteris'active','inactive',or'all'. Returnstypeeidr:partyQueryResults,whichcontains: PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults ContinuationTokenreturnedbyimplementationsthatinternallycachequeryresults. Itshouldbepassedinasthetokenargumentonsubsequentcallsasanaccelerator. P a g e |34 Version1.0120110407
EIDRAPIOverview
Forexample,"Fox"wouldreturntherecordsforFoxTelevisionand20thCenturyFox. Forthesearch,String,DisplayNameandSortNamearenormalized(spacescollapsed, punctuationremoved)butnottokenized,filteredforstopwords,orstemmed. Errors:standarderrorsandResultTooLong Thepagingparametersareusedasfollows: Internally,theRegistrykeepsalistofPartiessortedbySortName(orDisplayNameofSortNameisnot present.)SectionsofthissortedlistarereturnedusingtheFindPartiesFromCatalog()call. FindPartiesFromCatalog(string, roleFilter, activeFilter, page, pageSize, continuationToken) Seebelowforuseofpagingparametersandstring. roleFilterisanoptionallistofstringsoftypeeidr:administratorTypeType. activeFilteris'active','inactive',or'all'. Returnstypeeidr:partyQueryResults,whichcontains: PageSizemaxsizeofreturnedchunks(sameasinputparameterpageSize) MySizesizeofthischunk(equaltopageSizeexceptforthelastpage TotalPagestotalnumberofpagesthatcanbereturned PageNumnumberofthereturnedpage TotalResultstotalnumberofavailableresults ContinuationTokenreturnedbyimplementationsthatinternallycachequeryresults. Itshouldbepassedinasthetokenargumentonsubsequentcallsasanaccelerator. ResultsarereturnedwithpageSizeobjectsperbatch Thepagethpageofthatsizeisreturned.Page1isthefirstpage.Page0isarequestforall results. ContinuationTokenshouldbeavaluereturnedbythepreviouscallusingthisquery string,oremptyifthisisthefirstcallintheset.
EIDRAPIOverview
P a g e |35
Version1.0120110407
Alistof eidr:partyDOIType,inlexicalorderbySortName(orDisplayNameif SortNamedoesnotexist),forallpartiesfoundmatchingthesecriteria:Alistof eidr:partyDOIType forallparties o o o o whoseDisplayNamefieldcontainsstring thatmatchactiveFilter whoseAllowedRolescontainsoneormoreoftheelementsofroleFilter.If roleFilterisnotpresent,anyrolewillmatch stringisusedasfollows: TheemptystringmatchesallParties Lettersequence:returnsallpartieswhoseSortName(orDisplayNameif thereisnotSortName)startswiththelettersequence.Forexample"BBC" wouldreturntherecordsforBBC,BBCWorldwide,BBCCymru,BBC Scotland,andBBCAmerica. Lettersequence1lettersequence2:returnsallpartieswhoseSortName(or DisplayNameifthereisnotSortName)startswithsomethingbetween lettersequence1andlettersequence2,inclusive.Iflettersequence2isnot lexicallygreaterthanlettersequence1,allitemsfromlettersequence1 thoughtheendofthesortedlistofPartiesarereturned.Forinstance,"AB" returnsallPartieswhosenamesstartwithAorB. Notethatiflettersequence1andlettersequence2areidentical,thebehavioristhesameas forthesinglelettersequence.
Forthesearch,string,DisplayNameandSortNamearenormalized(spacescollapsed, punctuationremoved)butnottokenized,filteredforstopwords,orstemmed. Errors:standarderrorsandResultTooLong Thepagingparametersareusedasfollows: ResultsarereturnedwithpageSizeobjectsperbatch. Thepagethpageofthatsizeisreturned.Page1isthefirstpage.Page0isarequestforall results. ContinuationTokenshouldbeavaluereturnedbythepreviouscallusingthisquerystring, oremptyifthisisthefirstcallintheset. 4.2 PERMISSIONS Aregularrecordcanbecreated,modified,aliased,ordeleted.AnInDevelopmentrecordcanalsobe promoted.Itisalsopossibletoreadcertaintypesofadministrativeinformationaboutarecord. AParty(anditsUsers)canonlycreateanewrecordifithas'Registrant'intheAllowedRolesfield.
EIDRAPIOverview
P a g e |36
Version1.0120110407
AParty(anditsUsers)mustbeabletoreadanobjectinordertocreateormodifyanyinheritance, dependence,orlightweightrelationshipsinvolvingit.Forexample,anIsAdjunctTorelationshipcannotbe madetoanInDevobjectbyaPartythatisnotontheInDevobject'sReadACL. OtheractionsaregatedbyACLsontheindividualrecords.EachregularrecordhasanACLfor: Modify:cancontainentitiesthatareoftypeRegistrantorWriter.Requiredtomodifyanobject. Delete:cancontainentitiesthatareoftypeRegistrantorWriter.Requiredtoaliasordeletean object. ReadACL:cancontainentitiesthatareoftypeRegistrant,Writer,orReader.Requiredtoreadany ACL. WriteACL:cancontainentitiesthatareoftypeRegistrant.RequiredtomodifyanyACL. ReadProvenance:cancontainentitiesthatareoftypeRegistrant,Writer,orReader.Requiredto readtheprovenancemetadata.OnlytheRegistrationAuthoritycanmodifyarecord'sProvenance information.
ThefollowingtablesummarizespossiblepermissionsbasedontheRole.ForagivenObject,theassociated permissionsforaparticularParty(withaRole)maybemorerestrictivethanwhatsspecifiedinthetable. Role/Permission View Read ACL Registrant Writer Reader PrincipalAgent Yes Yes Yes Yes Yes Yes Yes Read Provenance Yes Yes Yes Yes Yes Yes Yes Modify Delete Write ACL Yes Yes Yes Yes Promote
WriteACL,andPromote,andwillnotsubsequentlybeabletobeaddedtotheACLsforModify,Delete, WriteACL,orPromoteonanyotherobjects. ReadACL (assetID, aclType) ReturnsalistofthePartiesonthespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. Errors:Standarderrors. ClearACL(assetID, aclType) RemovesallPartiesfromthespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. Errors:Standarderrors. AddToACL(assetID, aclType, partyID) AddspartyIDtothespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. PartyID isoftype eidr:partyDOIType. Errors:Standarderrors,andBadPartyifpartyIDisnotvalid. RemoveFromACL(assetID, aclType, partyID) RemovespartyIDfromthespecifiedACLforassetID,whichmustbeoftype eidr:assetDOIType. PartyID isoftype eidr:partyDOIType. Errors:Standarderrors,andBadPartyifpartyIDwasnotontheACL.
5. UTILITIES
5.1 DOIPROXY EIDRresolutionscanberequestedfromthestandardDOIproxy.Resolutionrequestsareoftheform:
http://dx.doi.org/<Handle prefix>/<Handle suffix>
Objectresolutionshavethestandardoptionalresolutiontypespecifier,e.g.,
http://dx.doi.org/10.5240/5551-2125-5512-1255-7FFF-3?locatt=type:Full
Inthefollowingtable,'ResolutionType'isthestringafterthecoloninthe?locatt=type:construction. (none)meansthatthetypespecifierisnotprovided. Proxyresolutionsfollowaliaschains,andbehaveliketheResolve()callwithfollowAliassetto true.SeeResolve()forinformationonspecialcasesfordeletedobjects,overnestedaliases,etc. EIDR item Prefix Resolution Type Returns P a g e |38 Version1.0120110407
EIDRAPIOverview
EIDR item
Party User
Prefix
10.5237 10.5238
Resolution Type
(none) (none)
Returns
doi:kernelMetadatawithadoi:referentPartyelement doi:kernelMetadatawithreferenttypeofRestricted doi:referentPartyelementwithanameof"EIDRUser"
6. PREDEFINEDOBJECTSANDCONSTANTS
6.1 TOMBSTONES Deletedobjectsarealiasedtoa'tombstone.'Becausethetombstoneobjectisoftype'Restricted',only threeofitsfieldshaveguaranteedvalues.Otherfieldsshouldnotbeused. Field
ID StructuralType ResourceName
Value
10.5240/00000000000000000000X Restricted "EIDRTombstoneObject"
Thetombstoneobjectisnotindexed,soitwillneverbereturnedfromqueries. 6.2 ERRORHANDLING Thestructuresusedforreturningerrorsareinapi.xsd Errorstringsandnumericerrorcodesareinapicommon.xsd 6.3 PREDEFINEDPARTIES Theparty10.5237/superpartyispredefinedandhasallallowedroles.Ithasapredefineduser 10.5238/superuser. 10.1000/ra5istheDOIfortheEIDRRegistrationAuthority;itisusedintheDOIKernelresolutionformat. 6.4 HANDLEPREFIXES TheHandleprefixesusedbytheregistryare: EIDRAPIOverview P a g e |39 Version1.0120110407
7. APPENDICES
7.1 SEASONSANDEPISODES Theinteractionsbetweenname,number,andtheIsOrderedflaginseasonsandseriesis: Seasons: SequenceNumberisrequiredforseasons. ResourceNameisrequiredforaseasonifparent.IsOrderedisfalse.
7.2 COMPLEXINHERITANCE Mostinheritablefieldsusesimpleinheritancethevalueistakendirectlyfromtheparent,whichinturn mayhavetakenitfromitsparent,andsoonuptheinheritancechainuntilanobjectisfoundthatdefines thefield.Inthesecases,afield'svalueisoneofeithertheselfdefinedmetadataortheinheritedmetadata. ResourceNameandPrimaryandsecondarylanguagesbehavedifferently,becauselanguagesandtitlescan bereplacedinaparticularobject(providinganewvalue)oraccreted(addinganewvaluetoapreexisting set).Inthesecases,thevaluefoundintheobject'sfullmetadataisnotnecessarilythesameaseitherthe selfdefinedortheinheritedmetadata,butcanbeacombinationofthings. 7.2.1. RESOURCENAME ResourceNameiscardinality1inbaseObjectInfoTypeitmustexistinafullyresolvedobjectand 01inselfDefinedBaseObjectInfoTypeandinheritedBaseObjectInfoType,whereitcan beeitherpresentontheobjectorinherited.Aresourcenamespecifiesthelanguageofthename,andthe classofthenameRelease,Working,Acronym,andsoon. TheReplacedAlternateResourceNamesflagbehavesasfollows:
EIDRAPIOverview
7.2.2. LANGUAGES PrimaryLanguage andSecondaryLanguageinthebasetypeareprovidedonlywhencreatinga rootobject. ArootobjectdefinesaPrimaryLanguageelement,andasetofoptionalSecondaryLanguage elements.Thesecontainonlylanguageinformation;titlesarespecifiedseparatelyusingthe ResourceNameandAlternateResourceNameelements. Thesetwofieldsarenotdirectlymodifiableinnonrootobjects.Instead,extralanguagesarespecifiedwith anIsLanguageVariantdependencerelationship,whichcomesintwoforms: Add:onlysecondarylanguagescanbespecified,andtheyareaddedtoanyinheritedsecondary languages.Theprimarylanguageisunchanged. Replace:Thissupportsthreevariants: o Primarylanguageonly:Theprimarylanguageisreplaced,andallsecondarylanguagesare removed. Primaryandoneormoresecondarylanguages:Theprimarylanguageisreplaced,allexisting secondarylanguagesareremoved,andthesecondarylanguagesintherequestareadded. Secondarylanguagesonly:Allsecondarylanguagesareremoved,andreplacedwiththe secondarylanguagesintherequest.Thesetisallowedtobeempty,inwhichcaseall secondarylanguagesareremoved.
EIDRAPIOverview
7.4 TEXTPROCESSING 7.2.3. FIELDRULES Therearethreekindsofmatches: TokenMatchthecheckismadefortheexistenceofthetokensinanyorderinthecandidate string.Thisusesthe<field> <string> <string>syntax. ExactMatchthecheckisdonefortheexistenceofanorderedsequenceoftokensinthecandidate string.Thisusesthe<field> "<string>"syntax. CompleteMatchchecksfortheexactexistenceoftheexactquerystringornot.Thisisgenerally usedforfieldscontainingcontrolledvocabularyorIDs,butcanalsobeusedonsometextfields.For P a g e |42 Version1.0120110407
EIDRAPIOverview
Match type
Token Exact
Normalize
Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes
Stem
No No No No No No No No No No No No No No No No No No No No No No Yes No Yes No
AlternateResourceName
Token Exact
DisplayName
Token Exact
md:PersonNametype/SortName
Token Exact
md:PersonNametype/FirstGivenName
Token Exact
md:PersonNametype/SecondGivenName
Token Exact
md:PersonNametype/FamilyName
Token Exact
md:PersonNametype/Suffix
Token Exact
md:PersonNametype/Moniker
Token Exact
Description
Token Exact
WrapperDetails
Token Exact
EIDRAPIOverview
P a g e |43
Version1.0120110407
Field
HouseSequence RegistrantExtra RegistrantPrivate AlternateID Anyfieldoftype componentReferenceType: EncodingInfo/xxxInfoBlock/Compone ntReference and EncodingInfo/WrapperInfoBlock/Com ponentInfo/componentReference FindPartiesByName FindPartiesFromCatalog
Match type
Complete Complete Complete Complete Total
Normalize
No No No No No
Stem
No No No No No
Yes Yes
No No
No No
Spacing Punctuation
.,;:^&!+=()[]{}<>~ #$/*@/ '(singlequote) "(doublequote) (hyphen)
Collapsing Punctuation
(apostrophe)
Stop Words
a,the,this,that,these,some,is,are,and,or,but, so,as,at,by,of,on,for,in,into,to,with,I,you, he,she,it,we,they,them,its,theirs
French
.,;:^&!+=()[]{}<>~
un,une,le,la,les,l,ce,ces,c,de,du,des,d,est,
EIDRAPIOverview
P a g e |44
Version1.0120110407
Language
Spacing Punctuation
#$/*@/ '(singlequote) "(doublequote) (hyphen) (apostrophe)
Collapsing Punctuation
Stop Words
sont,a,ont,ne,pas,n,et,ou,mais,que,qui,qu,, aux,sur,dans,en,par,avec,y,il,elle,ils,ells,lui, leurs,son,sa,ses,leur
Italian
ad,al,allo,ai,agli,all,agl,alla,alle,con,col,coi, da,dal,dallo,dai,dagli,dall,dagl,dalla,dalle,di, del,dello,dei,degli,dell,degl,della,delle,in,nel, nello,nei,negli,nell,negl,nella,nelle,su,sul, sullo,sui,sugli,sull,sugl,sulla,sulle,per,tra, contro,lui,lei,noi,loro,suo,sua,suoi,sue,lo,la, li,le,gli,ne,il,un,uno,una,ma,ed,se,perch, anche,come,dov,dove,che,chi,cui,non,pi, quale,quanto,quanti,quanta,quante,quello, quelli,quella,quelle,questo,questi,questa, queste,si,a,c,e,i,l,o,sono, un,unos,una,unas,el,los,la,las,este,esta,esto, estos,estas,ese,esa,eso,esos,esas,es,son,est, estn,hay,y,o,pero,de,en,para,como,con, por,sobre,el,ella,ellos,ellas,se,su,sus,suyo, suya,suyos,suyas
Spanish
German
(apostrophe) [Note:thismeans thatanapostrophe attheendofaword isdropped,andone inthemiddleofa wordfor abbreviations collapsesthetwo partstogether.]
EIDRAPIOverview
P a g e |45
Version1.0120110407
7.5 ESCAPINGXMLCHARACTERS SpecialXMLcharactersinaRegistryresponseareescapedasappropriate,regardlessofthetechnique (escapingorCDATA)usedintheoriginalrequest.Thespecialcharactersandtheirescapedrepresentation are Character " ' < > & Escape " ' < > &
7.6 MAPPINGEIDRFIELDSTODOIFIELDS Note: BaseObjectDataisoftypeeidr:baseObjectInfoType. Provenanceisoftypeeidr:provenanceInfoType PrincipalAgentisoftypeeidr:principalAgentType PartyResolutionisoftypeeidr:partyResolutionType DOI Kernel Subfield
primaryLanguage value type
EIDRAPIOverview
P a g e |46
Version1.0120110407
referentCreation.structuralType referentCreation.mode
referentCreation.character
referentCreation.type
referentCreation.PrincipalAgent
linkedCreation
Reservedforfutureusebasedonanobject's relationships
EIDRAPIOverview
P a g e |47
Version1.0120110407