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

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.

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>

Sample usage

curl -i \
     -H "Content-Type: application/xml" \
     -H "Authorization: Bearer <token>" \
     -d @PATH_TO_ONIX_PRODUCT_FILE \
     "https://api.bokbasen.io/metadata/import/onix/v1"
 
HTTP/1.1 202 Accepted
Date: Thu, 02 Oct 2014 12:24:28 GMT
Server: Apache-Coyote/1.1
Location: https://api.bokbasen.io/metadata/import/onix/v1/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. 

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. 

Sample usage 

curl -i \
     -H "Content-Type: image/jpeg" \
     -H "Authorization: Bearer <token>" \
     --data-binary @9788203218323_cover.jpg \
     "https://api.bokbasen.io/metadata/import/object/v1/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)

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>

Sample usage 

curl -i \
     -H "Content-Type: application/xml" \
     -H "Authorization: Bearer <token>" \
     "https://api.bokbasen.io/metadata/import/onix/v1/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.bokbasen.io/metadata/import/onix/v1/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.bokbasen.io/metadata/import/onix/v1/status/b64555a0-1d4b-472c-91e5-461a034a8fde</url>
        <registered>20141002142426</registered>
        <state>UNPROCESSED</state>
    </importItem>
</importItems>

Import Item Status (details)

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>

Sample usage 

curl -i \
     -H "Content-Type: application/xml" \
     -H "Authorization: Bearer <token>" \
     "https://api.bokbasen.io/metadata/import/onix/v1/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

See Authentication Service

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>