Import Service

The import service provides methods for sending metadata and objects to Bokbasen. All of these services requires authentication using the Authentication Service.


Revision History


DateVersionChanges
2015-01-151.0Import API released in production
2014-11-210.5Object import updated, changes type names, and completed with all object types
2014-10-290.4Object import API updated, <actionsCompleted> response in XML removed.
2014-09-190.3Sent for customer review. All services except object import described.
2014-09-160.2Draft for internal review
2014-09-080.1Draft Created


Onix Import

The Onix Import Service allows clients to post a single Onix Product for registration in the Bokbasen system. Data to be imported are included in the payload of the post request, and must be a valid XML-representation of a Product according to the Onix Standards for Books (see XSD) published by EDitEUR. If posted data validates as Onix the client receives a "202 Accepted" response with a Location header pointing to a service where the client can retrieve the current status of the import request. If validation fails the response will be "400 Bad request" with an error XML explaining the reason why validation fails.

URLhttps://api.boknett.no/metadata/import/onix
MethodPOST
Request headers AuthorizationRequired

The token acquired from the Authentication Service.

Formated "Boknett TGT-...."

DateRequiredThe timestamp the request was made. Must comply with RFC 1123 date formats.
Content-TypeRequiredapplication/xml
Request bodyXML (Onix 3.0.x Product)
Response bodyNone of success (202), error XML on validation error (400).
Response headersLocationURL to a service where the client can monitor the status of the current request. This URL contains the Import Item id of the request which is used to lookup the corresponding status. This will only be provided if the request is accepted.
Returns202Accepted
400Bad Request
401Unauthorized
500Internal Server Error

Response on Success

On Success (response code 202) the response header "Location" contains the link to the import item status that must be used to monitor import status.

Response on Validation error 

If messages does not validate a "400 Bad Request" is returned with the following XML structure as body.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<errors>
    <error>
		<ref></ref>
        <code></code>
        <message></message>
    <error>
<errors>
Element / AttributeDescription
errorsTop element, can contain multiple error elements
errorOne single error message
refInternal error reference. Include this if you are contacting Bokbasen about this error. 
codeError code used to categorize errors.
messageError message in clear text

Sample usage


curl -i -H "Content-Type: application/xml" -H "Authorization: Boknett TGT-137709-EXjxxuwvmPIzTgY1PXdTY6c5eVJ3esH6KnY9ulYYYfRTLxYvGZ-login.bokett.no" -H "Date: Thu, 02 Oct 2014 12:24:25 GMT" -d @PATH_TO_ONIX_PRODUCT_FILE "https://api.boknett.no/metadata/import/onix"
 
HTTP/1.1 202 Accepted
Date: Thu, 02 Oct 2014 12:24:28 GMT
Server: Apache-Coyote/1.1
Location: https://api.boknett.no/metadata/import/status/b64555a0-1d4b-472c-91e5-461a034a8fde
Content-Length: 0
Via: 1.1 api.boknett.webbe.no

Object Import


The Onix Import Service allows clients to post a single Object for registration in the Bokbasen system. 

URL

https://api.boknett.no/metadata/import/object/{id}/{type}/

Method

POST

Request headers 

Authorization

Required

The token acquired from the login service.

Formated "Boknett TGT-...."

Date

Required

The timestamp the request was made. Must comply with RFC 1123 date formats.

Content-Type

Required

Based on on content, see table below for valid content types per "type" parameter.

Request body

Binary file content

Response body

XML on validation error, none on 201.

Returns

201

Created

400

Bad Request

500

Internal Server Error

Here is a list of valid values for {type} in the URL which denotes which can of file you are submitting. For each type you can also see which value you can use as ID. As of today all object types use EAN, but new types with different identifiers might be introduced in the future. Each type has a strict list of content types that are allowed, you must make sure that your content header 1) Is matching the binary content you are sending 2) Is on the list of allowed content types. If you have content types that are in use and is not in this list, please convert your file to an allowed content type, or contact Bokbasen to see if these can be added to the white list. 


{type}

{id}

Allowed "Content-type"

Comment

productimage

EAN

image/jpeg

Cover image for books or image of products, used in mentor and export service

audiosample

EAN

audio/mpeg

Audio sample used mostly for audio books (only MP3 files allowed)
appcoverEANimage/jpegCover image for ebooks (overrides productimage)
tableofcontentsEANapplication/pdfTable of contents delivered in pdf.

Sample usage 

curl -i -H "Content-Type: image/jpeg" -H "Authorization: Boknett TGT-137709-EXjxxuwvmPIzTgY1PXdTY6c5eVJ3esH6KnY9ulYYYfRTLxYvGZ-login.boknett.no" -H "Date: Thu, 02 Oct 2014 12:24:25 GMT" --data-binary @9788203218323_cover.jpg "https://api.boknett.no/metadata/import/object/9788200000334/productimage/"
 
HTTP/1.1 100 Continue
Via: 1.1 api.boknett.dev.webbe.no
  
HTTP/1.1 201 Created
Date: Fri, 31 Oct 2014 13:04:44 GMT
Server: Apache-Coyote/1.1
Content-Length: 0
Via: 1.1 api.boknett.no

Import Item Status (list)

URLhttps://api.boknett.no/metadata/import/status/all
MethodGET
Request
headers

Authorization

Required

The token acquired from the Authentication Service.

Formated "Boknett TGT-...."

DateRequiredThe timestamp the request was made. Must comply with RFC 1123 date formats.
Response
body
XML (List of importItems, see details below)
Returns200OK
400Bad Request
401Unauthorized
403Forbidden
500Internal Server Error

Response Body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<importItems>
    <importItem>
        <id></id>
		<url></url>
		<registered></registered>
        <state></state>
    </importItem>
    <importItem>
        <id></id>
		<url></url>
		<registered></registered>
        <state></state>
    </importItem>
</importItems>
Element / AttributeDescription
idThe unique id of the Import Item.
Sample: a47ad10b-58cc-4372-a567-0e2342c3d479 
urlURL to the detailed Import Item Status Service for this specific Import Item.
Sample: https://api.boknett.no/metadata/import/status/a47ad10b-58cc-4372-a567-0e2342c3d479 
registeredTimestamp for when the import item was received, provided in the format: yyyyMMddHHmmss
stateThe current state of the Import Item. Can be one of:
UNPROCESSED
COMPLETED
FAILED 


Sample usage 

curl -i -H "Content-Type: application/xml" -H "Authorization: Boknett TGT-137709-EXjxxuwvmPIzTgY1PXdTY6c5eVJ3esH6KnY9ulYYYfRTLxYvGZ-login.boknett.no" -H "Date: Thu, 02 Oct 2014 12:38:25 GMT" "https://api.boknett.no/metadata/import/status/all"
 
HTTP/1.1 200 OK
Date: Thu, 02 Oct 2014 12:40:52 GMT
Server: Apache-Coyote/1.1
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<importItems>
    <importItem>
        <id>2b6eea56-f448-4210-a1d3-2dd49479567d</id>
        <url>https://api.boknett.no/metadata/import/status/2b6eea56-f448-4210-a1d3-2dd49479567d</url>
        <registered>20141002101349</registered>
        <state>UNPROCESSED</state>
    </importItem>
    <importItem>
        <id>b64555a0-1d4b-472c-91e5-461a034a8fde</id>
        <url>https://api.boknett.no/metadata/import/status/b64555a0-1d4b-472c-91e5-461a034a8fde</url>
        <registered>20141002142426</registered>
        <state>UNPROCESSED</state>
    </importItem>
</importItems>

Import Item Status (details)

URLhttps://api.boknett.no/metadata/import/status/{ID}
MethodGET
Request
headers

Authorization

Required

The token acquired from the Authentication Service.

Formated "Boknett TGT-...."

DateRequiredThe timestamp the request was made. Must comply with RFC 1123 date formats.
Response
body
XML (importItem)
Returns200OK
400Bad Request
401Unauthorized
403Forbidden
500Internal Server Error


Response Body

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<importItem>
    <id></id>
	<registered></registered>
    <state></state>
	<errors>
    	<error>
	        <code></code>
    	    <message></message>
    	</error>
	</errors>
	<warnings>
    	<warning>
	        <code></code>
    	    <message></message>
    	</warning>
	</warnings>
</importItem>
Element / AttributeDescription
idThe unique id of the Import Item
Sample: a47ad10b-58cc-4372-a567-0e2342c3d479  
registeredtimestamp for when the import item was received
stateThe current state of the Import Item. Can be one of:
UNPROCESSED
COMPLETED
FAILED 
errorsComposite containing errors, if any. Element not present if no errors available.
warningsComposite containing warnings, if any. Element not present if no warnings available.
actionsCompletedList of actions completed based on import request. Currently this will only return which onix blocks that was imported
action.typeType of action that is completed. Currently the only possible value is "onixBlockImported"
action.value

Value related to the specific action type.

For action.type onixBlockImported the possible values are 1-6.


Sample usage 

curl -i -H "Content-Type: application/xml" -H "Authorization: Boknett TGT-137709-EXjxxuwvmPIzTgY1PXdTY6c5eVJ3esH6KnY9ulYYYfRTLxYvGZ-login.boknett.no" -H "Date: Thu, 02 Oct 2014 12:38:25 GMT" "https://api.boknett.no/metadata/import/status/b64555a0-1d4b-472c-91e5-461a034a8fde"
 
 
HTTP/1.1 200 OK
Date: Thu, 02 Oct 2014 12:39:06 GMT
Server: Apache-Coyote/1.1
Content-Type: application/xml
Via: 1.1 api.boknett.no
Transfer-Encoding: chunked
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<importItem>
    <id>b64555a0-1d4b-472c-91e5-461a034a8fde</id>
    <registered>20141002142426</registered>
    <state>UNPROCESSED</state>
</importItem>

Implementation guidelines

Authentication

Every "session" should start with requiring a ticket (TGT) from the Authentication Service. Since the ticket can expire the client should implement a method for requiring a new ticket when necessary. This is typically necessary when a "session" can last longer that the maximum age of a ticket (currently two hours). The ticket shall be included in all requests to the Import Services (Onix Import, Object Import and Import Item Status).

Onix Import

One Product per request

An Onix document consists of one ONIXMessage with one Header element and a number of Product elements. The Onix Import Service accepts POST's of one Onix Product per request - not a complete ONIXMessage.

(Information about sender that is normally extracted from the Onix Header is managed by the Authentication process and consequently not part of the exchanged data.)

The following scenarios will generate an error response:

  • POST of a complete ONIXMessage
  • POST of a Header element
  • POST of more than one Product elements


Sample XML of Onix Product

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Product xmlns="http://ns.editeur.org/onix/3.0/reference">
  <RecordReference>reference</RecordReference>
  <NotificationType>01</NotificationType>
  <ProductIdentifier>
    <ProductIDType>01</ProductIDType>
    <IDValue>12345</IDValue>
  </ProductIdentifier>
	.....
</Product>


Asynchronous process

The Onix Import service does not process the Onix Product completely immediately. The process consists of a initial synchronous validation and a separate asynchronous part. The client need to support handling of the asynchronous process. 

The response can return:

  • 202 (Accepted): The Product is "Received" and the response Location parameter includes a URL to the Import Item Service where the client can monitor the status of the newly posted Product. The client needs to keep track of the received Import Item Status (either by response Location header or Item id from response body) and do subsequent requests to the Import Item Status Service until the Item has status COMPLETED or FAILED.
  • Any other response code: The request failed. No Location header is returned. Error message is returned. Possible errors are invalid Onix, invalid Sender, system error. The client needs to handle the error message but does not need to do any further requests.

There is no limitation in the number of Products that can be created. A client can POST many products before checking status of the returned Import Items. 

The client can either keep track of each Import Item (request by ID) or use the Import Item Status list (list of Items).

A Product that is FAILED will not be acted upon by Bokbasen. It is the Senders responsibility to act upon FAILED Products and resubmit the Product with valid data.

Onix Blocks

A Sender is allowed to updated a limited number of Onix Blocks according to a pre defined rule set. Unallowed Onix Blocks present in the Product will be ignored by the Onix Import. The rule set might differ depending on who has updated the specific Product previously. Typically, if a publisher updates the Product the allowed Onix Blocks from the Distributor is limited for that specific Product.

The Import Item Status includes information of what Onix Blocks was imported in the actionsCompleted.action element.

A Onix Block can be excluded from the import due to:

  • The rule set. The Sender is not allowed to update that specific Block. (Note: It is not an error to send such Blocks). 
  • No data present. If a Onix Product does not contain elements in a Block the complete block is ignored. This is crucial to understand since it affects deletion of data.

Deletion of data

In Onix "Each Product record carries all available information about that product, even if the entire Product record is unchanged from a previous message." Implicitly "any data previously held, but not included in the new full update should be deleted".

In the Onix Import Service this rule is implemented per Onix Block. Data (elements in XML or fields in database terms) in a non-present Onix Block is not deleted. Data not present in a Onix Block that is present is interpreted as if the data should be deleted.

Examples:

  • A Onix Product contains Block 1 but not TitleDetail.SubTitle. This is interpreted as "SubTitle shall be deleted".
  • A Onix Product contains only Block 6 (not Block 1). SubTitle is not affected.

Validation

Before data is sent to the asynchronous process the API validates 

  1. That you have access to update the given product
  2. That the file validates according to Editeur's official XSD
  3. Some additional XML data validations to assure that fields that are required by bokbasen and the Norwegian publishing industry is in place. 

Example

  1. A Distributor is allowed to send Onix Blocks 1, 2, 4, 6.
  2. The distributor sends a Onix Product with Blocks 1, 2, 3, 4.
  3. Block 3 is ignored by the Onix Import Service since it is not allowed for distributors.
  4. The Publisher has previously sent updates on Onix Block 2 which excludes Onix Block 2 from any subsequent updates from the distributor for this specific Product. Block 2 is ignored.
  5. Onix Blocks 1 and 4 are processed and imported.
  6. When COMPLETED, the Item Status response will include information that Onix Blocks 1 and 4 has been processed. See example below.


<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<importItem>
    <id>a47ad10b-58cc-4372-a567-0e2342c3d479</id>
	<registered>20140907233000</registered>
    <state>COMPLETED</state>
    <warnings>
		<warning>
			<code>xxx</code>
			<message>Some warning text</message>
		</warning>
    </warnings>
</importItem>