1. Home
  2. Programming
  3. EIDR REST API
  4. REST API – Common HTTP Headers

REST API – Common HTTP Headers

Common HTTP Headers

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.

HTTP Request Headers

The EIDR API uses the following HTTP request headers for all service requests.

Header NameRequiredDescription
AcceptOptionalThe MIME type of the accepted response. Defaults to “text/xml”. The value should be text/xml.
Accept-EncodingOptionalEnables 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.
AuthorizationConditional. 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-ResponseOptional, 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-TypeRequired for the POST methodThe 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-VersionThe version of the EIDR REST API for the requestSetting 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).
HTTP Request Headers

NOTE: EIDR ignores any other request headers if specified in a request.

Authentication and Authorization

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.

POST Data

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)&lt;
> (greater than)&gt;
& (ampersand)&amp;
XML character escaping

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:

Header NameRequiredDescription
Content-DispositionRequiredWhere 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-EncodingRequiredThis is always binary:
Content-Transfer-Encoding: binary
HTTP Multi-part MIME Headers

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--

De-Duplication Modes

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.

De-Dupe ModeStatusDescription
normalDefaultIf 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.
manualOptionalIf 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.[1]
acceptRestrictedWill return an error if submitted by anyone other than the Superparty.
reviewRestrictedWill return an error if submitted by anyone other than the Superparty.

Table 4: De-Duplication Modes

For example:

<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>

Codes and Descriptions

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 CodeStatus TypeNote
0successIndicates that the API request succeeded.
1system errorShould be reported to EIDR support
2registry in read-only errorShould be reported to EIDR support unless this Registry is a mirror or is scheduled to be read-only.
3invalid requestAn 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.
4authentication errorInvalid credentials including an Inactive account.
5authorization errorThe operation requires credentials. Or the credentials provided are not authorized to perform this operation. Check with EIDR support about this operation.
6bad token errorThere is a problem with the token ID such as one that is not syntactically valid or does not exist.
7bad query errorThere is a problem with a content record query. This could include a typographical error in an EIDR field name.
8bad id errorThere is a problem with the content ID such as one that is not syntactically valid or does not exist.
9syntax errorInvalid XML in a query or write operation. Examples: an incorrect namespace declaration; an element not closed; or incorrect case for an enumerated value.
10result too longA result was too large to fit in a REST response. This can be caused by requesting too large a page size in queries.
11duplicate partyAn Administration API error
12duplicate userAn Administration API error
13bad partyThere is a problem with the Party ID such as it does not exist
14bad userThere is a problem with the User ID such as it is syntactically invalid or does not exist.
15all validAn Administration API error
16wrong groupAn Administration API error
17invalidAn Administration API error
18no parentThe object of a GetParent request is itself the root of a content record tree.
19no childrenThe object of a GetChildren request is itself a leaf of a content record tree.
20has dependentsAn Administration API error.
21duplicate serviceAn Administration API error.
22bad serviceInvalid Video Service ID.
23compatibility errorThe operation cannot be supported with the requested value in the EIDR-Version header.
API Status Codes

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 CodeStatus TypeNote
0successThe data operation Request succeeded.
1duplicateRequest failed because the system identified an existing record with duplicate metadata. One or more Duplicate ID elements will accompany this status.
2pendingThis 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”.
3authorization errorYour credentials are not authorized to perform this operation. Check with EIDR support about this operation.
4validation errorThe 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).
5other errorRequest 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.
6rejectedA 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.
Operation Status Codes

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 CodeStatus TypeNote
1batch receivedThe 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.
2batch queuedStatus 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”.
3invalid batchA 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.
Batch Status Codes

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”.

HTTP Response Headers

The EIDR API responds with the following headers:

Header NameDescription
Content-TypeThe Internet Media (MIME) Type of the response sent by EIDR to its clients which is always: text/xml; charset=UTF-8
Content-EncodingThe compression applied to the content if any. If applied, this will only be: gzip
Content-LengthThe length of the response in bytes. If not present, then Transfer-Encoding applies.
Transfer-EncodingThe compression applied to the data transmitted if applicable (as in gzip Content-Encoding). If applied, this will only be: chunked
DateThe time of the response. For example: Mon, 08 Dec 2014 23:00:38 GMT
EIDR-VersionThis will always be the current version. For example: 2.6.0
HTTP Response Headers

See Also


[1] 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.

Updated on April 9, 2021

Was this article helpful?

Related Articles