Read the 3.4 Release Notebook to learn about all the changes introduced in 3.4.

The following changes were made to the REST API.

• Use of the apiToken as a query parameter is deprecated. Use it in the Authorization header instead. See the "Authentication" section below.
• Changes to request body to create a new submission.
• Changes to submission titles. They may now include HTML in the fullTitle, title, and subtitle properties.
• Changes to the submission property, submissionProgress. It is now a string, not an integer.
• Changes to the stats endpoints.
• Changes to the endpoints to manage email templates.

The following new endpoints have been added.

• New endpoint to save a submission for later.
• New endpoint to submit a submission.
• New endpoint to copy a submission file from one file stage to another.
• New endpoints to manage a publication's contributors.
• New endpoints to create and register DOIs.
• New endpoints to record editorial decisions.
• New endpoints to manage institutions.
• New endpoints to get mailables.

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

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 by using the 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.

The apiToken will not validate if the api_secret_key setting has not been set in the application's config.inc.php file.

Your API token can be found by going to User Profile > API Key in the application. Add the API Token in an Authorization header with every request made to the API.

Authorization: Bearer eyJ0e...6vJU

Most API endpoints follow the same convention to return subsequent pages of results. The following would return the second "page" of results, if each page contained 30 results.

https://example.com/api/v1/submissions?count=30offset=30

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.