This usage guide is for versions 3.3 and below.
This document describes how to interact with the REST API provided by PKP applications. It is a technical document intended for software developers who wish to build applications to interact with OJS or OMP.
Skip to the technical references.
The REST API will respond to HTTP requests with the requested data in JSON format. When receiving POST or PUT requests, it expects to receive a payload formatted in JSON.
Use the following to access the /submissions endpoint when an application is hosted at https://example.com/.
https://example.com/api/v1/submissions
A multi-journal OJS installation must access endpoints from each journal’s URL.
https://example.com/journalpath/api/v1/submissions
Installations that do not use mod_rewrite must include index.php.
https://example.com/index.php/journalpath/api/v1/submissions
Installations which have set disable_path_info to On in the configuration file must use query parameters. Use of this method is discouraged.
https://example.com/index.php?journal=journalpath&endpoint=/api/v1/submission
Administrators can access some endpoints, such as /contexts, at a site-wide endpoint that spans all journals.
https://example.com/_/api/v1/contexts
Only authenticated users can access the REST API endpoints. Authentication can be done with cookies or an API token.
Cookie-based authentication can be used when you are making a request from the same domain name as the application. When a request is made from the user’s browser, the browser will send the cookies to the server.
A CSRF token must be sent with every POST, PUT or DELETE request when using cookie-based authentication. Read more about the CSRF Token.
Your API token can be found by going to User Profile > API Key in the application. Add a query parameter, apiToken, to any request to the API.
https://example.com/api/v1/submissions?apiToken=eyJ0e...6vJU
The
apiTokenwill not validate if theapi_secret_keysetting has not been set in the application’sconfig.inc.phpfile.
The base endpoint for an entity will return a list of those entities. Typically, you can use query parameters in the request to filter, sort and paginate the requests.
The following will return only submissions that have been submitted to sections with an ID of 1 or 2.
https://example.com/api/v1/submissions?sectionIds[]=1§ionIds[]=2
When a query parameter is accepted as an array, it will often accept the parameter as a comma-separated string.
https://example.com/api/v1/submissions?sectionIds=1,2
The following will return submissions in alphabetical order.
https://example.com/api/v1/submissions?orderBy=title&orderDirection=ASC
The following will return the second “page” of results, if each page contained 30 results.
https://example.com/api/v1/submissions?count=30offset=30
Consult the API Reference for a full list of supported query parameters.
All PKP applications are multilingual. Multilingual fields will be provided as a JSON object with keys specifying the locale codes. The following response shows the title property of a publication in English and Canadian French.
{
"title": {
"en_US": "Young people from an immigrant background and their choice of post-secondary orientation in Montreal",
"fr_CA": "Jeunes issus de l’immigration et choix d’orientation au postsecondaire à Montréal"
},
...
}
This is the same even when an installation only uses a single language.
{
"title": {
"fr_CA": "Jeunes issus de l’immigration et choix d’orientation au postsecondaire à Montréal"
},
...
}
When sending POST or PUT requests, the REST API will expect the data it receives to be passed in the same format.
Some responses will include a _href property. The value of this property will be a URL to the full version of this object in the REST API.
{
"_href": "http://example.com/api/v1/submissions/219"
...
}
Files can be uploaded by sending a POST request to the /temporaryFiles endpoint. It will return a file ID which can be used in subsequent requests. Let’s look at an example.
To upload a logo for a context (journal, press, or preprint server), upload the image by sending a POST request to /temporaryFiles. A successful upload will generate the following response:
{
id: 123
}
To save the logo to the context, send a PUT request to /contexts/1:
{
pageHeaderLogoImage: {
temporaryFileId: 123,
altText: "Logo for the Journal of Public Knowledge"
}
}
The file will be moved from the temporary directory to its public location, overwriting any existing logo.
Temporary files can only be managed by the the user who uploaded the file. If a user passes a temporaryFileId for a file they did not upload themselves, they will receive an authorization error.
A few of the REST API endpoints are for internal use only and may be changed without notice. These endpoints are grouped in the Backend section of the references. Developers should expect that any integrations which make use of these endpoints could break from one version to the next.
Developers should update the API documentation whenever their code modifies a request or response. The API endpoints and query parameters are defined in an OpenAPI v3 specification
Several definitions are left undefined in the specification file.
"definitions": {
"Author": "author",
...
}
These definitions are drawn from the entity schemas, and will be merged with the source file when the API docs are built.
Technical references are available for the following software packages.
Documentation for the REST APIs in OMP and OPS is not yet available. These applications share many of the same endpoints as OJS, but the documentation has not yet been prepared.
We use Postman to test our APIs. You can import our OJS collection (last updated 2020-12-21).