Import Service
The import service provides methods for sending metadata and objects to Bokbasen. All of these services requires authentication using the Authentication Service .
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
- 1.1 Onix Import
- 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 |
The token acquired from the Authentication Service. Formated "Boknett TGT-...." Required header: | ||
Method |
| ||
Request headers |
| Required | The token acquired from the Authentication Service. Audience: |
| Required |
| |
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. | |
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 |
|---|---|
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.noObject Import
The Onix Import Service allows clients to post a single Object for registration in the Bokbasen system.
Payload is limited to 10MB
URL |
The token acquired from the login service. Formated "Boknett TGT-...." Required header: | ||
Method |
| ||
Request headers |
| Required | The token acquired from the login service. Audience: |
| 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) |
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.noImport Item Status (list)
URL |
The token acquired from the Authentication Service. Formated "Boknett TGT-...." Required header: | ||
Method |
| ||
Request |
| Required | The token acquired from the Authentication Service Audience: |
Response | XML (List of importItems, see details below) | ||
Returns | 200 | OK | |
400 | Bad Request | ||
401 | Unauthorized | ||
403 | Forbidden | ||
500 | Internal 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 / Attribute | Description |
|---|---|
id | The unique id of the Import Item. |
url | URL to the detailed Import Item Status Service for this specific Import Item. |
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: |
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)
URL |
The token acquired from the Authentication Service. Formated "Boknett TGT-...." Required header: | ||
Method |
| ||
Request |
| Required | The token acquired from the Authentication Service Audience: |
Response | XML (importItem) | ||
Returns | 200 | OK | |
400 | Bad Request | ||
401 | Unauthorized | ||
403 | Forbidden | ||
500 | Internal 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 / Attribute | Description |
|---|---|
id | The unique id of the Import Item |
registered | timestamp for when the import item was received |
state | The current state of the Import Item. Can be one of: |
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
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
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
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.
<?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>