The import service provides methods for sending metadata and objects to Bokbasen. All of these services requires authentication using the https://bokbasen.jira.com/wiki/spaces/api/pages/2994962433 .

New Authentication & URLs introduced Q2 2024

- 1.1 Onix Import
  - 1.1.1 Response on Success
  - 1.1.2 Response on Validation error
  - 1.1.3 Sample usage
- 1.2 Object Import
  - 1.2.1 Sample usage
- 1.3 Import Item Status (list)
  - 1.3.1 Response Body
  - 1.3.2 Sample usage
- 1.4 Import Item Status (details)
  - 1.4.1 Response Body
  - 1.4.2 Sample usage
2 Implementation guidelines
- 2.1 Authentication
- 2.2 Onix Import
  - 2.2.1 One Product per request
  - 2.2.2 Asynchronous process
  - 2.2.3 Onix Blocks
  - 2.2.4 Deletion of data
- 2.3 Validation
  - 2.3.1 Example

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.

URL	`https://api.bokbasen.io/metadata/import/onix/v1` `https://api.boknett.no/metadata/import/onix` The token acquired from the Authentication Service. Formated "Boknett TGT-...." Required header: `Date`. The timestamp the request was made. Must comply with RFC 1123 date formats.
Method	`POST`
Request headers	`Authorization`	Required	The token acquired from the https://bokbasen.jira.com/wiki/spaces/api/pages/2994962433. Audience: `https://api.bokbasen.io/metadata/`
	`Content-Type`	Required	`application/xml`
Request body	XML (Onix 3.0.x Product)
Response body	None of success (202), error XML on validation error (400).
Response headers	Location	URL 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.
Returns	202	Accepted
	400	Bad Request
	401	Unauthorized
	500	Internal 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 / Attribute	Description

Element / Attribute	Description
errors	Top element, can contain multiple error elements
error	One single error message
ref	Internal error reference. Include this if you are contacting Bokbasen about this error.
code	Error code used to categorize errors.
message	Error message in clear text

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.

Payload will be limited to 6MB

When moving to the new URL (Q2 2024). Contact us if that is a problem for you.

URL	`https://api.bokbasen.io/metadata/import/object/v1/{id}/{type}` `https://api.boknett.no/metadata/import/object/{id}/{type}/` The token acquired from the login service. Formated "Boknett TGT-...." Required header: `Date`. The timestamp the request was made. Must comply with RFC 1123 date formats.
Method	`POST`
Request headers	`Authorization`	Required	The token acquired from the login service. Audience: `https://api.bokbasen.io/metadata/`
	`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

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

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)

URL	`https://api.bokbasen.io/metadata/import/onix/v1/status/all` `https://api.boknett.no/metadata/import/status/all` The token acquired from the Authentication Service. Formated "Boknett TGT-...." Required header: `Date`. The timestamp the request was made. Must comply with RFC 1123 date formats.
Method	`GET`
Request headers	`Authorization`	Required	The token acquired from the https://bokbasen.jira.com/wiki/spaces/api/pages/2994962433 Audience: `https://api.bokbasen.io/metadata/`
Response body	XML (List of importItems, see details below)
Returns	200	OK
	400	Bad Request
	401	Unauthorized
	403	Forbidden
	500	Internal Server Error

Response Body

Element / Attribute	Description

Element / Attribute	Description
id	The unique id of the Import Item. Sample: a47ad10b-58cc-4372-a567-0e2342c3d479
url	URL 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
registered	Timestamp for when the import item was received, provided in the format: yyyyMMddHHmmss
state	The current state of the Import Item. Can be one of: UNPROCESSED COMPLETED FAILED

Sample usage

Import Item Status (details)

URL	`https://api.bokbasen.io/metadata/import/onix/v1/status/{id}` `https://api.boknett.no/metadata/import/status/{ID}` The token acquired from the Authentication Service. Formated "Boknett TGT-...." Required header: `Date` The timestamp the request was made. Must comply with RFC 1123 date formats.
Method	`GET`
Request headers	`Authorization`	Required	The token acquired from the Audience: `https://api.bokbasen.io/metadata/`
Response body	XML (importItem)
Returns	200	OK
	400	Bad Request
	401	Unauthorized
	403	Forbidden
	500	Internal Server Error

Response Body

Element / Attribute	Description

Element / Attribute	Description
id	The unique id of the Import Item Sample: a47ad10b-58cc-4372-a567-0e2342c3d479
registered	timestamp for when the import item was received
state	The current state of the Import Item. Can be one of: UNPROCESSED COMPLETED FAILED
errors	Composite containing errors, if any. Element not present if no errors available.
warnings	Composite containing warnings, if any. Element not present if no warnings available.
actionsCompleted	List of actions completed based on import request. Currently this will only return which onix blocks that was imported
action.type	Type 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

Implementation guidelines

Authentication

See

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

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

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

Example

A Distributor is allowed to send Onix Blocks 1, 2, 4, 6.
The distributor sends a Onix Product with Blocks 1, 2, 3, 4.
Block 3 is ignored by the Onix Import Service since it is not allowed for distributors.
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.
Onix Blocks 1 and 4 are processed and imported.
When COMPLETED, the Item Status response will include information that Onix Blocks 1 and 4 has been processed. See example below.