Advance notice - DOAJ API: breaking change coming, + new version number

Please note that DOAJ is making a change to its API which will break existing integrations. This is an advance notice.

On September 23rd 2021, we will reinstate a compulsory question in the DOAJ application form which asks for the open access (OA) start date. This will affect applications or updates to existing journals that are sent to us via the API. All applications and updates received after 23rd September will be required to have an OA start date present in the JSON.

We will also bump the API version from 2.0.0 to 3.0.0.

More details will be available very soon, including the specific JSON requirements. Please look out for further notifications here in the PKP Forum.

If you belong to an organisation that routinely sends new applications or updates to DOAJ via our API and you would like a dedicated email to your inbox, please contact me with your email address, DOAJ account number(s) and the name of the publisher you represent.

As always, if you have any questions, do please get in touch!

Dom Mitchell,
DOAJ Operations Manager

3 Likes

Hi Dominic,

Thanks a lot for the advice. As you know well, this kind of changes need time to let community and PKP developers do the proper changes and testing in their plugins and workflows.

Talking about time… reading your announcement is not clear to me how big will be the window to do the changes. I mean, is the specification published? Is there a sandbox with the new api? There will be a “grace period” during which both apis (the old api and the new one) will work or does it all end on the 23rd of this month?

Thanks a lot for your time and the great work you all are doing with DOAJ.

Cheers,
m.

1 Like

Hello Marc, thanks for your great questions.

Just to underline that the breaking change only applies to publishers submitting applications or updates to us via the API.

Even though the API version is being bumped from 2 to 3, all existing integrations for depositing metadata will continue to work. We will bump the API version from 2.0.0 to 3.0.0, in line with Semantic Versioning https://semver.org/

We will set up the following URL routes and redirects
/api/v1 → /api/v3
/api/v2 → /api/v3
/api → /api/v3
/api/v3

The current implementation will be under /api/v3. So all existing article metadata deposits will continue to work.

The final changes to the new application JSON are not yet published.

The change will come into effect on 23rd Sept so after that date, old-style applications and updates will not work.

I hope that helps but let me know if you have more questions.

1 Like

For those of you who are interested, here is an example of the JSON for a new application to DOAJ, with the oa_start date field in place. It is a field in bibjson object and is just a number. It must be a year with the format YYYY

{
“bibjson”: {
“alternative_title”: “Alternative Title”,
“apc”: {
“max”: [
{
“currency”: “GBP”,
“price”: 2
}
],
“url”: “http://apc.com”,
“has_apc”: “True”
},
“article”: {
“license_display”: [
“Embed”
],
“license_display_example_url”: “http://licence.embedded”,
“orcid”: “True”,
“i4oc_open_citations”: “False”
},
“boai”: “True”,
“copyright”: {
“author_retains”: “True”,
“url”: “http://copyright.com
},
“deposit_policy”: {
“has_policy”: “True”,
“service”: [
“Sherpa/Romeo”,
“Store it”
],
“url”: “http://deposit.policy
},
“discontinued_date”: “2001-01-01”,
“editorial”: {
“review_process”: [
“Open peer review”,
“some bloke checks it out”
],
“review_url”: “http://review.process”,
“board_url”: “http://editorial.board
},
“eissn”: “9876-5432”,
“is_replaced_by”: [
“2222-2222”
],
“institution”: {
“name”: “Society Institution”,
“country”: “US”
},
“keywords”: [
“word”,
“key”
],
“language”: [
“EN”,
“FR”
],
“license”: [
{
“type”: “Publisher’s own license”,
“BY”: “True”,
“NC”: “True”,
“ND”: “False”,
“SA”: “False”,
“url”: “http://licence.url
}
],
“oa_start”: 2021,
“other_charges”: {
“has_other_charges”: “True”,
“url”: “http://other.charges
},
“pid_scheme”: {
“has_pid_scheme”: “True”,
“scheme”: [
“DOI”,
“ARK”,
“PURL”,
“PIDMachine”
]
},
“pissn”: “1234-5678”,
“plagiarism”: {
“detection”: “True”,
“url”: “http://plagiarism.screening
},
“preservation”: {
“has_preservation”: “True”,
“service”: [
“LOCKSS”,
“CLOCKSS”,
“A safe place”
],
“national_library”: [
“Trinity”,
“Imperial”
],
“url”: “http://digital.archiving.policy
},
“publication_time_weeks”: 8,
“publisher”: {
“name”: “The Publisher”,
“country”: “US”
},
“ref”: {
“oa_statement”: “http://oa.statement”,
“journal”: “http://journal.url”,
“aims_scope”: “http://aims.scope”,
“author_instructions”: “http://author.instructions.com”,
“license_terms”: “http://licence.url
},
“replaces”: [
“1111-1111”
],
“subject”: [
{
“scheme”: “LCC”,
“term”: “Economic theory. Demography”,
“code”: “HB1-3840”
},
{
“scheme”: “LCC”,
“term”: “Social Sciences”,
“code”: “H”
}
],
“title”: “The Title”,
“waiver”: {
“has_waiver”: “True”,
“url”: “http://waiver.policy
}
},
“admin”: {
“current_journal”: “0000ca40e1ac4cdcbf09be63c8fc25a2”
}
}

Our incoming application documentation (which will be updated on 23rd Sept), will be changed to look like this:

{
“admin”: {
“current_journal”: “string”,
},
“bibjson”: {
“alternative_title”: “string”,
“apc”: {
“has_apc”: true,
“max”: [
{
“currency”: “string”,
“price”: 0
}
],
“url”: “string”
},
“article”: {
“i4oc_open_citations”: true,
“license_display”: [
“string”
],
“license_display_example_url”: “string”,
“orcid”: true
},
“boai”: true,
“copyright”: {
“author_retains”: true,
“url”: “string”
},
“deposit_policy”: {
“has_policy”: true,
“is_registered”: true,
“service”: [
“string”
],
“url”: “string”
},
“discontinued_date”: “2021-09-15”,
“editorial”: {
“board_url”: “string”,
“review_process”: [
“string”
],
“review_url”: “string”
},
“eissn”: “string”,
“institution”: {
“country”: “string”,
“name”: “string”
},
“is_replaced_by”: [
“string”
],
“keywords”: [
“string”
],
“language”: [
“string”
],
“license”: [
{
“BY”: true,
“NC”: true,
“ND”: true,
“SA”: true,
“type”: “string”,
“url”: “string”
}
],
“oa_start”: 1900,
“other_charges”: {
“has_other_charges”: true,
“url”: “string”
},
“pid_scheme”: {
“has_pid_scheme”: true,
“scheme”: [
“string”
]
},
“pissn”: “string”,
“plagiarism”: {
“detection”: true,
“url”: “string”
},
“preservation”: {
“has_preservation”: true,
“national_library”: [
“string”
],
“service”: [
“string”
],
“url”: “string”
},
“publication_time_weeks”: 0,
“publisher”: {
“country”: “string”,
“name”: “string”
},
“ref”: {
“aims_scope”: “string”,
“author_instructions”: “string”,
“journal”: “string”,
“license_terms”: “string”,
“oa_statement”: “string”
},
“replaces”: [
“string”
],
“subject”: [
{
“code”: “string”,
“scheme”: “string”,
“term”: “string”
}
],
“title”: “string”,
“waiver”: {
“has_waiver”: true,
“url”: “string”
}
}
}

We are moving the date of this change back one week. Go-live is now 30th September.