As is the case with all REST implementations using HTTP, all requests and responses vary in the HTTP method used for requests, HTTP headers, and the actual data transmitted between the server and the clients. The following three sub-sections summarize the headers used for all the EIDR requests and responses.
The EIDR API uses the following HTTP request headers for all service requests.
|Accept||Optional||The MIME type of the accepted response. Defaults to “text/xml”. The value should be text/xml.|
|Accept-Encoding||Optional||Enables HTTP compression. If not present, then defaults to no compression. If specified, the value should be gzip. If the Registry uses compression, then the Content-Encoding response header will confirm.|
|Authorization||Conditional. Required for only access-controlled service requests. See Section “Public Services” to find which ones are access-controlled and which are not.||The required authentication and authorization credentials. See the “Authentication and Authorization” section below for the value.|
|Immediate-Response||Optional, but conditional. Refer to the EIDR Registry Technical Overview to know which operations can be “true” and which cannot.||This is a proprietary header that applies only to registration requests. It is a flag that if true indicates that the service should process the request immediately. The default is “false”.|
|Content-Type||Required for the POST method||The value can be text/xml or multipart/form-data in EIDR requests. Text/xml is recommended since it is simpler and the request can be validated with an XML validator.|
|EIDR-Version||The version of the EIDR REST API for the request||Setting this to a value less than the current version will return a response compatible with the request. (See Registry Version Compatibility.) If this is not possible, it will be return a 23 code (compatibility error).|
NOTE: EIDR ignores any other request headers if specified in a request.
The EIDR API uses the standard HTTP Authorization header to pass both the authentication and authorization credentials. The EIDR API uses a proprietary authentication scheme (“Eidr”) that extends standard HTTP Basic authentication to incorporate both an EIDR User and an EIDR Party into the credentials. A pseudo-grammar of the HTTP Authorization request header is shown below:
Authorization = "Eidr" + " " + UserID + ":" + PartyID + ":" + PasswordShadow; PasswordShadow = Base64(MD5(Password));
NOTE: The “Eidr” authentication scheme token is case-insensitive.
NOTE: As required in Base64 encoding, the resulting string must include padding out to a multiple of 4 characters by appending “=” characters. In the case of a 128-bit MD5 hash, the base64 encoding results in a 24-character string ending in “==”. Some APIs, such as Perl’s md5_base64() function, leave the addition of padding to the caller. Also note that the base64 encoding of the MD5 hash is of the binary string, not of the hexadecimal text string.
NOTE: Certain characters commonly used in the XML elements need to be escaped. Most XML libraries perform this escaping automatically. The XML characters that require escaping are listed in the table below.
|Character glyph (name)||XML Escape|
|” (double quote)||"|
|‘ (apostrophe, back quote)||'|
|< (less than)||<|
|> (greater than)||>|
For POST requests, the data can use the multipart/form-data MIME type (see IETF RFC 7578).
In the multipart case, the POST data must begin with a boundary. The initial boundary is followed by these headers:
|Content-Disposition||Required||Where the value of the name parameter usually matches the salient part of the path of the URI for the service. For example name=”query” for the /EIDR/query service.|
|Content-Transfer-Encoding||Required||This is always binary:|
NOTE: These lines must be terminated CRLF (per RFC 882 and 2045). The final header and the body must be terminated by two CRLF sequences. The part is terminated by another boundary. A sample POST file for a query (where the boundary is “—313159”):
---314159 Content-Disposition: form-data; name=query Content-Transfer-Encoding: binary <?xml version="1.0" encoding="UTF-8"?> <Request xmlns="http://www.eidr.org/schema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Operation> <Query> <Expression>/FullMetadata/BaseObjectData/Status valid</Expression> <PageNumber>1</PageNumber><PageSize>25</PageSize> </Query> </Operation> </Request> ---314159--
When in non-immediate (asynchronous) mode, Create and Modify can specify a particular de-dupe mode by adding a dedupMode attribute to the Operation tag.
|normal||Default||If no dedupMode attribute is present, then normal mode applies. Any records requiring manual review to resolve will be referred to EIDR Operations. The user can check the status on the provided Token ID to learn the final state of the transaction.|
|manual||Optional||If present, all non-gap records (records that would not automatically be issued an EIDR ID) are referred to EIDR Operations for manual review, even if the automated review process has identified an existing duplicate ID. This is most often used when the user disagrees with the automated de-duplication response and believes that the submitted record is unique and warrants a new ID.|
|accept||Restricted||Will return an error if submitted by anyone other than the Superparty.|
|review||Restricted||Will return an error if submitted by anyone other than the Superparty.|
Table 4: De-Duplication Modes
<Request xmlns="http://www.eidr.org/schema" xmlns:md="http://www.movielabs.com/md" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Operation> <Create type="CreateBasic"> <Basic> ... </Basic> </Create> </Operation> </Request>
Is the same as:
<Request xmlns="http://www.eidr.org/schema" xmlns:md="http://www.movielabs.com/md" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Operation dedupMode="normal"> <Create type="CreateBasic"> <Basic> ... </Basic> </Create> </Operation> </Request>
While the following will force manual review:
<Request xmlns="http://www.eidr.org/schema" xmlns:md="http://www.movielabs.com/md" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Operation dedupMode="manual"> <Create type="CreateBasic"> <Basic> ... </Basic> </Create> </Operation> </Request>
EIDR will always respond with an HTTP Status Code of “200 OK”. If there is an error, it will be in the response body. For example:
<?xml version="1.0" encoding="UTF-8"?> <Response xmlns="http://www.eidr.org/schema" version="2.0"> <Status><Code>8</Code><Type>bad id error</Type></Status> </Response>
The set of applicable Status Codes to the API request is as follows:
|Status Code||Status Type||Note|
|0||success||Indicates that the API request succeeded.|
|1||system error||Should be reported to EIDR support|
|2||registry in read-only error||Should be reported to EIDR support unless this Registry is a mirror or is scheduled to be read-only.|
|3||invalid request||An API (URI) that does not exist including missing a required parameter. May also include an incorrect HTTP operation on a valid URI (such as a GET on a registration). Could also be POST multipart data that is syntactically invalid such as missing required headers or if the end-of-line characters are not CR-LF.|
|4||authentication error||Invalid credentials including an Inactive account.|
|5||authorization error||The operation requires credentials. Or the credentials provided are not authorized to perform this operation. Check with EIDR support about this operation.|
|6||bad token error||There is a problem with the token ID such as one that is not syntactically valid or does not exist.|
|7||bad query error||There is a problem with a content record query. This could include a typographical error in an EIDR field name.|
|8||bad id error||There is a problem with the content ID such as one that is not syntactically valid or does not exist.|
|9||syntax error||Invalid XML in a query or write operation. Examples: an incorrect namespace declaration; an element not closed; or incorrect case for an enumerated value.|
|10||result too long||A result was too large to fit in a REST response. This can be caused by requesting too large a page size in queries.|
|11||duplicate party||An Administration API error|
|12||duplicate user||An Administration API error|
|13||bad party||There is a problem with the Party ID such as it does not exist|
|14||bad user||There is a problem with the User ID such as it is syntactically invalid or does not exist.|
|15||all valid||An Administration API error|
|16||wrong group||An Administration API error|
|17||invalid||An Administration API error|
|18||no parent||The object of a GetParent request is itself the root of a content record tree.|
|19||no children||The object of a GetChildren request is itself a leaf of a content record tree.|
|20||has dependents||An Administration API error.|
|21||duplicate service||An Administration API error.|
|22||bad service||Invalid Video Service ID.|
|23||compatibility error||The operation cannot be supported with the requested value in the EIDR-Version header.|
When the Request is a content Operation, the Response also includes an Operation Status code and will usually include a Details field. For example:
<RequestStatusResults> … <OperationStatus> <Token>1312315566343000884</Token> <Status> <Code>4</Code> <Type>validation error</Type> <Details>Referent Type must be one of "TV", "Movie", "Short", "Web"</Details> </Status> </OperationStatus> </RequestStatusResults>
The set of Operation Status Codes is as follows:
|Status Code||Status Type||Note|
|0||success||The data operation Request succeeded.|
|1||duplicate||Request failed because the system identified an existing record with duplicate metadata. One or more Duplicate ID elements will accompany this status.|
|2||pending||This status normally occurs only in asynchronous processing. The state applies initially while the request is being processed, which might take several seconds. If it takes longer than that then likely the request is pending because the system identified an existing record that is a potential duplicate, in which case the registration will be manually evaluated. In all cases, this token should be polled until its status is “success” or “duplicate” or “rejected”.|
|3||authorization error||Your credentials are not authorized to perform this operation. Check with EIDR support about this operation.|
|4||validation error||The request failed because it did not satisfy data validation rules. For example, an attempt was made to modify a record to have an incompatible Referent Type (such as convert a Movie to a Series).|
|5||other error||Request failed due to uncategorized error. Contact EIDR support for details. NOTE: If the error was the result of a registry service failure, then a clarifying note will be included in the message details: Please notify EIDR Operations if you receive one of these errors so we can research and correct the underlying cause.|
|6||rejected||A request in manual deduplication failed due to a problem with the record. This is not common. You should obtain guidance from EIDR Operations for correcting the error.|
All Operations statuses are terminal except for “pending”.
When the request consists of a batch with multiple operations, a Batch status applies. The set of Batch Status Codes is as follows:
|Status Code||Status Type||Note|
|1||batch received||The batch has been fully read in, but no status for its individual operations is available. This is the state in the initial registration response. It is not a terminal state, but is transient and is usually only seen when the system is under heavy load. The token can be polled until its state reaches terminal status.|
|2||batch queued||Status is available for all the operations tokens. While this state is terminal for a batch, it does not mean that all tokens are in a terminal state. Specifically, a token could be “pending”.|
|3||invalid batch||A terminal status for batches that begin processing but terminate in an error before being parsed into individual operations. This includes batches with invalid user tokens. This can also result from abnormal operation of the Registry, which should be reported to EIDR support.|
NOTE: Under special circumstances (brought about by an internal registry communications issue), records submitted as synchronous (immediate mode) may be unilaterally converted by the registry into asynchronous (non-immediate mode) transactions. In this case, instead of responding to the synchronous transaction with the applicable EIDR ID, the registry returns a system-generated transaction Token and the message “system busy, request has been converted to asynchronous”.
The EIDR API responds with the following headers:
|Content-Type||The Internet Media (MIME) Type of the response sent by EIDR to its clients which is always: text/xml; charset=UTF-8|
|Content-Encoding||The compression applied to the content if any. If applied, this will only be: gzip|
|Content-Length||The length of the response in bytes. If not present, then Transfer-Encoding applies.|
|Transfer-Encoding||The compression applied to the data transmitted if applicable (as in gzip Content-Encoding). If applied, this will only be: chunked|
|Date||The time of the response. For example: Mon, 08 Dec 2014 23:00:38 GMT|
|EIDR-Version||This will always be the current version. For example: 2.6.0|
 For example, when submitting a new registration for a numbered sequel where most of the title, the director, cast, production companies, etc. are all the same, the automated review process could incorrectly match this to a prior installation in the franchise instead of giving it a new EIDR ID.