{"type":"doc","content":[{"type":"panel","attrs":{"panelIconId":"1f50d","panelIcon":":mag:","panelIconText":"🔍","panelColor":"#E3FCEF","panelType":"custom"},"content":[{"type":"paragraph","content":[{"text":"See subpages for API-specifications","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"children","parameters":{"macroParams":{},"macroMetadata":{"macroId":{"value":"a3023811-9bca-40ae-89fe-6a710b69ac47"},"schemaVersion":{"value":"2"},"title":"Child pages"}},"localId":"d6c377f8-928e-4314-9f81-47cf7c2b389a"}},{"type":"paragraph","content":[{"text":"The export service provides alternatives for retrieving metadata and objects from Bokbasen. This pages contains general information covering all export services, see individual sub pages for the different data and formats that can be retrieved.","type":"text"},{"type":"hardBreak"}]},{"type":"extension","attrs":{"layout":"default","extensionType":"com.atlassian.confluence.macro.core","extensionKey":"toc","parameters":{"macroParams":{"minLevel":{"value":"1"},"maxLevel":{"value":"7"}},"macroMetadata":{"macroId":{"value":"40deeb99f788546f9c1778d77ad0fefb"},"schemaVersion":{"value":"1"},"title":"Table of Contents"}},"localId":"4839b0bc-ae69-46b4-af32-38a98a919145"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Pagination","type":"text"}]},{"type":"paragraph","content":[{"text":"All reports will require one of two parameters; ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code"}]},{"text":" or ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":". The usage of the two parameters differs slightly. The HTTP response will always contain a token that represents a specific \"internal timestamp\" and can be used as a \"cursor\". This token can be used in the next request to get all changes since the last request. ","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Parameters","type":"text"}]},{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":2496,"id":"75adce2d-1391-46c8-bef9-421c03a4c12d","collection":"contentId-48955432","type":"file","height":840}},{"type":"caption","content":[{"text":"Initial with ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code"}]},{"text":" then with ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" (persist ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" from each session)","type":"text"}]}]},{"type":"paragraph"},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"mediaSingle","attrs":{"layout":"center"},"content":[{"type":"media","attrs":{"width":1312,"id":"90693044-9a02-476a-b0b0-60cd52b563c1","collection":"contentId-48955432","type":"file","height":1496}},{"type":"caption","content":[{"text":"Recursive calls until ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" doesn’t change","type":"text"}]}]},{"type":"paragraph"}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"heading","attrs":{"level":3},"content":[{"text":"Next","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Using the ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" parameter is the recommended way to invoke the report service. It is also the only possible way to implement incremental updates. The HTTP response from all report services will include a header containing a token that represents a specific \"internal timestamp\" that can be used as a \"cursor\". This token shall be passed with the ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" parameter in the subsequent request in order to retrieve all updates since the last request. This requires the customer to save the obtained token from each response and use it in the following request. If the token is lost, a new token can easily be obtained by making a new request using an older ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" or the ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code"}]},{"text":" parameter.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"After","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Using the ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code"}]},{"text":" parameter will allow clients to request records updated since a specific time. The parameter has a human readable format ","type":"text"},{"text":"yyyyMMddHHmmss","type":"text","marks":[{"type":"code"}]},{"text":". The only recommended usage of the ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code"}]},{"text":" parameter is (1) when non incremental updates are requested (for example all records updated last 2 months) or (2) when the token is lost. A response to a request with an after parameter will include a new cursor in the header as long as the resulting report is not empty. Using the ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code"}]},{"text":" parameter for incremental updates can result in duplicated updates or \"missed\" updates. (The cause for this is that the timestamp on which both ","type":"text"},{"text":"next","type":"text","marks":[{"type":"code"}]},{"text":" and ","type":"text"},{"text":"after","type":"text","marks":[{"type":"code"}]},{"text":" is based, can be set to a value that is before current time.)","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pagesize","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"All reports have a default pagesize which is also the maximum pagesize. The client is free to choose a suitable pagesize between 1 and this maximum. If pagesize is omitted, or the requested pagesize exceeds the maximum, the services will handle the request using the default pagesize. All clients requesting reports should use the pagination facility when fetching a large number of records.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Response headers","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Next Response","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"header","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Next","type":"text","marks":[{"type":"code"}]},{"text":" response header is always present. When the current response does not contain any records the Next response header is unchanged.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Link Response header","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"Link","type":"text","marks":[{"type":"code"}]},{"text":" response header is only present as long as there are more pages to process. When the current response does not contain any records the Link response header is not present.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best practice","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Using the ","type":"text"},{"text":"Link","type":"text","marks":[{"type":"code"}]},{"text":" response header is the recommend method to implement pagination. The client should keep sending requests as long as the Link response header is present. After the initial request the ","type":"text"},{"text":"Link","type":"text","marks":[{"type":"code"}]},{"text":" response header should be used in every subsequent request. ","type":"text"},{"type":"hardBreak"},{"text":"It is also possible to implement pagination using the ","type":"text"},{"text":"Next","type":"text","marks":[{"type":"code"}]},{"text":" response header. If so, the client should keep sending requests as long as the ","type":"text"},{"text":"Next","type":"text","marks":[{"type":"code"}]},{"text":" response header does change from the preceding request.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Error Handling","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Feedback","type":"text"}]},{"type":"paragraph","content":[{"text":"In case the request fails due to validation of request headers or input parameters the client will receive a response consisting of an xml explaining the cause of failure. The elements of the error xml are listed below. For some errors there may be additional elements included for better explanation of the error cause. For non-xml formatted reports the response will be in plain text instead of xml.","type":"text"},{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"HTTP/1.1 HTTP_STATUS_CODE MESSAGE\nDate: Tue, 01 Apr 2014 10:49:04 GMT\nContent-Type: application/xml\n \n\n\n\t\n\t\t\n\t\t\n\t\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Restrictions ","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"90937cf0-6353-4817-88e5-2533ec8717ff"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[511.0]},"content":[{"type":"paragraph","content":[{"text":"Restriction","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[338.0]},"content":[{"type":"paragraph","content":[{"text":"Current value","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[511.0]},"content":[{"type":"paragraph","content":[{"text":"Default (and max) pagesize for ONIX","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[338.0]},"content":[{"type":"paragraph","content":[{"text":"200","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[511.0]},"content":[{"type":"paragraph","content":[{"text":"Default (and max) pagesize for Object Report","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[338.0]},"content":[{"type":"paragraph","content":[{"text":"5000","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[511.0]},"content":[{"type":"paragraph","content":[{"text":"Maximum age of Object reference link","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[338.0]},"content":[{"type":"paragraph","content":[{"text":"24 hours","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Pagination and Pagesize sample","type":"text"}]},{"type":"expand","attrs":{"title":"See examples"},"content":[{"type":"paragraph","content":[{"text":"Request with after and thereafter a request using the returned Link header.","type":"text"}]},{"type":"codeBlock","content":[{"text":"> curl -i \\\n -H \"Authorization: Bearer \" \\\n 'https://api.bokbasen.io/metadata/export/onix/v2?subscription=extended&pagesize=100&after=20140501120000'\n\nDate: Wed, 11 Jun 2014 19:11:20 GMT\nServer: Apache-Coyote/1.1\nNext: MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=\nLink: ; rel=\"next\"\nContent-Type: application/xml\nTransfer-Encoding: chunked\n\n\n... (1-100 records of 150 returned)\n\n\n> curl -i \\\n -H \"Authorization: Bearer \" \\\n 'https://api.bokbasen.io/metadata/export/onix/v2?next=MTI1MTUzNzhjMGQzIzE0Njc1YmFjNDlmIzhmMmU5YTU=&subscription=extended&pagesize=100'\n\nDate: Wed, 11 Jun 2014 19:12:45 GMT\nServer: Apache-Coyote/1.1\nNext: MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=\nLink: ; rel=\"next\"\nContent-Type: application/xml\nTransfer-Encoding: chunked\n\n\n... (101-150 of 150 records returned)\n\n \n> curl -i \\\n -H \"Authorization: Bearer \" \\\n 'https://api.bokbasen.io/metadata/export/onix/v2?next=MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=&subscription=extended&pagesize=100'\n\nDate: Wed, 11 Jun 2014 19:12:45 GMT\nServer: Apache-Coyote/1.1\nNext: MTI1MTUzNzhjMTBjIzE0Njc1YmUyZjY0IzhmMzJhNWM=\nContent-Type: application/xml\nTransfer-Encoding: chunked\n \n(No more records. Next unchanged. Link not present in Response)","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Parameter Error","type":"text"}]},{"type":"expand","attrs":{"title":"See examples"},"content":[{"type":"paragraph","content":[{"text":"Request with valid Authorization token and Date. But is missing mandatory parameter subscription.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"> curl -i \\\n -H \"Authorization: Bearer \" \\\n https://api.bokbasen.io/metadata/export/onix/v2?after=20140319100000\n \nHTTP/1.1 400 Bad Request\nContent-Type: application/xml\nTransfer-Encoding: chunked\nServer: Jetty(8.1.14.v20131031)\n\n\n \n subscription\n may not be null\n \n","type":"text"}]},{"type":"paragraph"},{"type":"paragraph","content":[{"text":"Request with valid Authorization token and Date. But is missing next or after parameter.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"> curl -i \\\n -H \"Authorization: Bearer \" \\\n https://api.bokbasen.io/metadata/export/onix/v2?subscription=basic\n \nHTTP/1.1 400 Bad Request\nContent-Type: application/xml\nTransfer-Encoding: chunked\nServer: Jetty(8.1.14.v20131031)\n\n\n \n nextAndAfterValid\n Either parameter next or after must be given. Not both.\n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Authorization Header Error (Bearer)","type":"text"}]},{"type":"expand","attrs":{"title":"See examples"},"content":[{"type":"paragraph","content":[{"text":"Expired or invalid token, or missing ","type":"text"},{"text":"Bearer","type":"text","marks":[{"type":"code"}]},{"text":" prefix all give ","type":"text"},{"text":"401","type":"text","marks":[{"type":"code"}]}]},{"type":"codeBlock","content":[{"text":"> curl -i \\\n -H \"Authorization: LETMEIN\" \\\n https://api.bokbasen.io/metadata/export/onix/v2?subscription=basic&after=20140319100000\n \nHTTP/1.1 401 Forbidden\nwww-authenticate: Bearer scope=\"export:onix\" error=\"invalid_token\" error_description=\"token contains an invalid number of segments\"","type":"text"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"System Error","type":"text"}]},{"type":"expand","attrs":{"title":"See example"},"content":[{"type":"paragraph","content":[{"text":"When the request is fine, but an unexpected error occurs at the server side, the client will receive the following response.","type":"text"}]},{"type":"codeBlock","attrs":{"language":"xml"},"content":[{"text":"HTTP/1.1 500 Server Error\nContent-Type: application/xml\n\n\n \n SystemError\n Something went wrong, please contact Bokdatabasen for more information\n \n","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Referenced documents","type":"text"}]},{"type":"table","attrs":{"layout":"default","width":760.0,"localId":"efc4d1df-e074-4929-8eaa-62815d0378ac"},"content":[{"type":"tableRow","content":[{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[238.0]},"content":[{"type":"paragraph","content":[{"text":"Document","type":"text"}]}]},{"type":"tableHeader","attrs":{"colspan":1,"rowspan":1,"colwidth":[612.0]},"content":[{"type":"paragraph","content":[{"text":"Description","type":"text"}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[238.0]},"content":[{"type":"paragraph","content":[{"text":"Onix documentation","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[612.0]},"content":[{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"editeur.org","type":"text","marks":[{"type":"link","attrs":{"href":"http://editeur.org"}}]},{"text":" where descriptions, schemas and etc is located.","type":"text"},{"type":"hardBreak"},{"text":"http://www.editeur.org/83/Overview/","type":"text","marks":[{"type":"link","attrs":{"href":"http://www.editeur.org/83/Overview/"}}]},{"type":"hardBreak"},{"text":"Bokbasens use of Onix is described here: ","type":"text"},{"text":"ONIX3","type":"text","marks":[{"type":"link","attrs":{"href":"https://bokbasen.jira.com/wiki/spaces/api/pages/51347469"}}]}]}]}]},{"type":"tableRow","content":[{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[238.0]},"content":[{"type":"paragraph","content":[{"text":"Bokbasen XML Specification","type":"text"}]}]},{"type":"tableCell","attrs":{"colspan":1,"rowspan":1,"colwidth":[612.0]},"content":[{"type":"paragraph","content":[{"text":"Separate specification of Bokbasen XML and the different subscriptions.","type":"text"},{"type":"hardBreak"},{"text":"\"Bokbasen XML_export_EKSTERN.xlsx\" ","type":"text"},{"type":"hardBreak"},{"text":"Delivered on request. ","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}