Public Knowledge Project Documentation

https://docs.pkp.sfu.ca/
Admin
The Public Knowledge Project (PKP) provides user guides, developer documentation, and publishing...
Tokens:326,401
Snippets:3,406
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Multilingual Field Example (Single Language)

Source: https://docs.pkp.sfu.ca/dev/api/usage.html

Even when an installation uses only a single language, multilingual fields are returned in the same JSON object format.

```json
{
	"title": {
		"fr_CA": "Jeunes issus de l’immigration et choix d’orientation au postsecondaire à Montréal"
	},
	...
}
```

--------------------------------

### Paginating Submissions

Source: https://docs.pkp.sfu.ca/dev/api/usage.html

This example demonstrates how to paginate through the list of submissions. You can control the number of results per page (`count`) and the offset for the starting point (`offset`).

```APIDOC
## GET /api/v1/submissions

### Description
Retrieves a paginated list of submissions.

### Method
GET

### Endpoint
/api/v1/submissions

### Parameters
#### Query Parameters
- **count** (integer) - Optional - The number of results to return per page.
- **offset** (integer) - Optional - The number of results to skip from the beginning.

### Request Example
```http
https://example.com/api/v1/submissions?count=30&offset=30
```
```

--------------------------------

### Get Site Theme Response Sample

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.2.html

Sample JSON response for a successful GET request to the /site/theme endpoint, indicating the theme plugin path and any theme options.

```json
{
  "themePluginPath": "string",
  "...": "string"

}
```

--------------------------------

### Usage Guide for Older Versions

Source: https://docs.pkp.sfu.ca/dev/api

A guide detailing the usage of the REST API for older versions of OJS, OMP, and OPS applications.

```APIDOC
## OJS/OMP/OPS REST API Usage Guide (Older Versions)

### Description
This guide covers the usage of the REST API for older versions of PKP applications, including OJS, OMP, and OPS. It is intended for users who need to interact with these applications programmatically.

### Method
(Details for specific methods are not provided in the source text.)

### Endpoint
(Details for specific endpoints are not provided in the source text.)

### Parameters
(Details for specific parameters are not provided in the source text.)

### Request Example
(No request examples are provided in the source text.)

### Response
(No response examples are provided in the source text.)
```

--------------------------------

### Get Announcements Response Sample

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.3.html

This is a sample JSON response for a successful GET request to the /announcements endpoint, including pagination and announcement item details.

```json
{
  "itemsMax": 0,
  "items": [
    {
      "_href": "http://example.com",
      "assocId": 0,
      "assocType": 0,
      "dateExpire": "string",
      "datePosted": "string",
      "description": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
},
      "descriptionShort": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
},
      "id": 0,
      "title": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
},
      "typeId": 0
}
]

}
```

--------------------------------

### Response Sample: List of Contexts (200 OK)

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.2.html

Example JSON response for a successful request to list contexts, showing the structure of context items including IDs, names, and enabled status.

```json
{
  "itemsMax": 0,
  "items": [
    {
      "_href": "http://example.com",
      "abbreviation": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
},
      "acronym": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
},
      "description": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
},
      "enabled": true,
      "id": 0,
      "journalThumbnail": {
        "type": null,
        "properties": null,
        "en_US": { },
        "fr_CA": { }
},
      "name": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
},
      "seq": 0,
      "url": "string",
      "urlPath": "string"
}
]

}
```

--------------------------------

### Publication Views Response Sample

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.3.html

Example JSON response for the GET /stats/publications endpoint, showing view counts and publication details.

```json
[
  {
    "abstractViews": 0,
    "galleyViews": 0,
    "pdfViews": 0,
    "htmlViews": 0,
    "otherViews": 0,
    "publication": {
      "_href": "string",
      "fullTitle": {
        "en_US": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "id": 0,
      "shortAuthorString": "string",
      "urlPublished": "string",
      "urlWorkflow": "string"
}
}

]
```

--------------------------------

### UI Library Pre-commit Hook Output Example

Source: https://docs.pkp.sfu.ca/dev/contributors

This output shows the expected result when a commit is made and pre-commit hooks are successfully executed for the ui-library repository.

```bash
$ git commit -m "pkp/pkp-lib#1234 Example commit"
 > running pre-commit hook: lint-staged
✔ Preparing...
✔ Running tasks...
✔ Applying modifications...
✔ Cleaning up...
[i7191_submission_wizard 8f35a50] pkp/pkp-lib#1234 Example commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 example.js


```

--------------------------------

### PHP Type Hinting Example

Source: https://docs.pkp.sfu.ca/dev/contributors

Illustrates the use of type hints for function parameters and return types in PHP.

```php
use APP\user\User;

class Example
{
    public function getUser(int $id): User
    {
        //
    }
}


```

--------------------------------

### Record Submission Decision with Actions

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.4.html

This example demonstrates recording a submission decision with multiple actions, including sending emails to authors and reviewers, and initiating a payment. Note that recipients for the author email are empty, indicating default recipients are used.

```json
{
  "decision": 2,
  "reviewRound": 123,
  "round": 1,
  "actions": [
    {
      "attachments": [
        {
          "name": "example-upload.pdf",
          "temporaryFileId": 1,
          "documentType": "pdf"
},
        {
          "name": "example-submission-file.pdf",
          "submissionFileId": 1,
          "documentType": "pdf"
},
        {
          "name": "example-library-file.pdf",
          "libraryFileId": 1,
          "documentType": "pdf"
}
],
      "bcc": "example@pkp.sfu.ca",
      "cc": "example@pkp.sfu.ca",
      "id": "notifyAuthors",
      "locale": "en",
      "recipients": [ ],
      "subject": "Example email subject",
      "body": "<p>Example email body.</p>"
},
    {
      "attachments": [
        {
          "name": "example-upload.pdf",
          "temporaryFileId": 1,
          "documentType": "pdf"
},
        {
          "name": "example-submission-file.pdf",
          "submissionFileId": 1,
          "documentType": "pdf"
},
        {
          "name": "example-library-file.pdf",
          "libraryFileId": 1,
          "documentType": "pdf"
}
],
      "bcc": "example@pkp.sfu.ca",
      "cc": "example@pkp.sfu.ca",
      "id": "notifyReviewers",
      "locale": "en",
      "recipients": [
        1,
        2
],
      "subject": "Example email subject",
      "body": "<p>Example email body.</p>"
},
    {
      "requestPayment": true,
      "id": "payment"
}
]

}
```

--------------------------------

### Submissions Endpoint Access

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.4.html

Demonstrates how to access the `/submissions` endpoint for a single-journal installation, a multi-journal installation, and an installation not using mod_rewrite.

```APIDOC
## Accessing the /submissions Endpoint

### Description
Provides the base URLs for accessing the `/submissions` API endpoint under different OJS installation configurations.

### Endpoint Examples

- **Single Journal Installation:**
  `https://example.com/api/v1/submissions`

- **Multi-Journal Installation:**
  `https://example.com/journalpath/api/v1/submissions`

- **Installation without mod_rewrite:**
  `https://example.com/index.php/journalpath/api/v1/submissions`
```

--------------------------------

### Request Payload Example

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.4.html

This snippet shows an example of the JSON payload that can be sent in a request to the API.

```APIDOC
## Request Payload Example

### Description
This is an example of the JSON payload structure for creating or updating a submission.

### Content Type
application/json

### Payload Structure
```json
{
  "abstract": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "accessStatus": 0,
  "categoryIds": [
    0
  ],
  "citationsRaw": "string",
  "copyrightHolder": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "copyrightYear": 0,
  "coverImage": {
    "type": null,
    "properties": null,
    "en": {
      "temporaryFileId": 0,
      "dateUploaded": "string",
      "uploadName": "string",
      "altText": "string"
    },
    "fr_CA": {
      "temporaryFileId": 0,
      "dateUploaded": "string",
      "uploadName": "string",
      "altText": "string"
    }
  },
  "coverage": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "dataAvailability": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "datePublished": "string",
  "disciplines": [
    "string"
  ],
  "doiId": 0,
  "hideAuthor": false,
  "issueId": 0,
  "keywords": [
    "string"
  ],
  "languages": [
    "string"
  ],
  "lastModified": "string",
  "licenseUrl": "string",
  "pages": "string",
  "prefix": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "primaryContactId": 0,
  "pub-id::publisher-id": "string",
  "rights": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "sectionId": 0,
  "seq": 0,
  "source": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "status": 1,
  "subjects": [
    "string"
  ],
  "submissionId": 0,
  "subtitle": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "supportingAgencies": [
    "string"
  ],
  "title": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "type": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "urlPath": "string",
  "version": 0
}
```
```

--------------------------------

### Pre-commit Hook Output Example

Source: https://docs.pkp.sfu.ca/dev/contributors

This output shows the expected result when a commit is made and pre-commit hooks are successfully executed for general application repositories.

```bash
$ git commit -m "pkp/pkp-lib#1234 Example commit"
husky > pre-commit (node v14.17.3)
✔ Preparing...
✔ Running tasks...
✔ Applying modifications...
✔ Cleaning up...
[main 1abc72ca2a] pkp/pkp-lib#1234 Example commit
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 example.php


```

--------------------------------

### Response Sample (200 OK)

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.4.html

This snippet shows an example of a successful JSON response from the API.

```APIDOC
## Response Sample (200 OK)

### Description
This is an example of a successful JSON response when retrieving submission details.

### Content Type
application/json

### Response Body Structure
```json
{
  "_href": "http://example.com",
  "abstract": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "accessStatus": 0,
  "authors": [
    {
      "affiliation": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "biography": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "competingInterests": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "country": "string",
      "email": "string",
      "familyName": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "fullName": "string",
      "givenName": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "id": 0,
      "includeInBrowse": true,
      "locale": "string",
      "orcid": "string",
      "preferredPublicName": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "publicationId": 0,
      "seq": 0,
      "url": "string",
      "userGroupId": 0,
      "userGroupName": "string"
    }
  ],
  "authorsString": "string",
  "authorsStringIncludeInBrowse": "string",
  "authorsStringShort": "string",
  "categoryIds": [
    0
  ],
  "citations": [
    "string"
  ],
  "citationsRaw": "string",
  "copyrightHolder": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "copyrightYear": 0,
  "coverImage": {
    "type": null,
    "properties": null,
    "en": {
      "dateUploaded": "string",
      "uploadName": "string",
      "altText": "string"
    },
    "fr_CA": {
      "dateUploaded": "string",
      "uploadName": "string",
      "altText": "string"
    }
  },
  "coverage": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "dataAvailability": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "datePublished": "string",
  "disciplines": [
    "string"
  ],
  "doiObject": {
    "contextId": 0,
    "doi": "string",
    "id": 0,
    "registrationAgency": "string",
    "resolvingUrl": "string",
    "status": 1
  },
  "fullTitle": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "galleys": [
    {
      "doiObject": {
        "contextId": 0,
        "doi": "string",
        "id": 0,
        "registrationAgency": "string",
        "resolvingUrl": "string",
        "status": 1
      },
      "file": {
        "_href": "http://example.com",
        "assocId": 0,
        "assocType": 515,
        "caption": "string",
        "copyrightOwner": "string",
        "createdAt": "string",
        "creator": {
          "en": "Filename",
          "fr_CA": "Nom de fichier"
        },
        "credit": "string",
        "dateCreated": "string",
        "dependentFiles": [
          {}
        ],
        "description": {
          "en": "Filename",
          "fr_CA": "Nom de fichier"
        },
        "documentType": "string",
        "fileId": 0,
        "fileStage": 2,
        "genreId": 0
      }
    }
  ]
}
```
```

--------------------------------

### Get Submission Participants

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.3.html

Retrieves all participants assigned to a specific submission. This endpoint is useful for getting a general list of individuals involved in a submission.

```json
[
  {
    "_href": "string",
    "disabled": true,
    "email": "string",
    "fullName": "string",
    "groups": [
      {
        "abbrev": {
          "en_US": "Filename",
          "fr_CA": "Nom de fichier"
        },
        "id": 0,
        "name": {
          "en_US": "Filename",
          "fr_CA": "Nom de fichier"
        },
        "permitSelfRegistration": true,
        "recommendOnly": true,
        "roleId": 0,
        "showTitle": true
      }
    ],
    "id": 0,
    "orcid": "string",
    "userName": "string"
  }

]
```

--------------------------------

### Create Announcement Response (200 OK)

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.4.html

This is a sample successful response (200 OK) after creating an announcement. It includes all provided details plus additional fields like the announcement ID and posting date.

```json
{
  "_href": "http://example.com",
  "assocId": 0,
  "assocType": 0,
  "dateExpire": "string",
  "datePosted": "string",
  "description": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "descriptionShort": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "id": 0,
  "image": {
    "name": "string",
    "uploadName": "string",
    "dateUploaded": "string",
    "altText": "string"
  },
  "title": {
    "en": "Filename",
    "fr_CA": "Nom de fichier"
  },
  "typeId": 0,
  "url": "http://example.com"
}
```

--------------------------------

### Sample Success Response (200)

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.4.html

Example JSON response for a successful request to the /users/reviewers endpoint. It includes reviewer details such as affiliation, completion times, and active/completed review counts.

```json
{
  "itemsMax": 0,
  "items": [
    {
      "_href": "string",
      "affiliation": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "averageReviewCompletionDays": 0,
      "dateLastReviewAssignment": "string",
      "disabled": true,
      "fullName": "string",
      "gossip": {
        "en": "Filename",
        "fr_CA": "Nom de fichier"
      },
      "groups": [
        {
          "abbrev": {
            "en": "Filename",
            "fr_CA": "Nom de fichier"
          },
          "abbrevLocaleKey": "string",
          "contextId": 0,
          "id": 0,
          "isDefault": true,
          "name": {
            "en": "Filename",
            "fr_CA": "Nom de fichier"
          },
          "nameLocaleKey": "string",
          "permitMetadataEdit": true,
          "permitSelfRegistration": true,
          "recommendOnly": true,
          "roleId": 16,
          "showTitle": true
        }
      ],
      "id": 0,
      "interests": [
        {
          "id": 0,
          "interest": "string"
        }
      ],
      "reviewsActive": 0,
      "reviewsCompleted": 0,
      "reviewsCancelled": 0,
      "reviewsDeclined": 0,
      "userName": "string"
    }
  ]
}
```

--------------------------------

### Get All Mailables Response Sample

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.4.html

This JSON object represents a sample response for the GET /mailables endpoint, detailing a single mailable class configuration.

```json
[
  {
    "_href": "https://example.org/publicknowledge/api/v1/mailables/DISCUSSION_NOTIFICATION_COPYEDITING",
    "dataDescriptions": {
      "journalName": "The journal's name",
      "journalUrl": "The URL to the journal's homepage",
      "...": "All prepared data"
    },
    "description": "This email is sent when a discussion is created or replied to in the copyediting stage.",
    "emailTemplateKey": "DISCUSSION_NOTIFICATION_COPYEDITING",
    "fromRoleIds": [
      17,
      4097,
      65536
    ],
    "groupIds": [
      "copyediting"
    ],
    "name": "Discussion (Copyediting)",
    "supportsTemplates": true,
    "toRoleIds": [
      17,
      4097,
      65536
    ]
  }
]
```

--------------------------------

### PHP PascalCase and camelCase Example

Source: https://docs.pkp.sfu.ca/dev/contributors

Demonstrates the use of PascalCase for class names and camelCase for function and variable names in PHP.

```php
use PKP\user\UserCache;

class UserIdentityRecord
{
    public function getUser(int $userId): User
    {
        $userCache = $this->getFromCache(UserCache::class, $userId);
        if ($userCache) {
            return $userCache;
        }

        return Repo::user()->get($userId);
    }
}


```

--------------------------------

### Get a List of Submissions (JSON Response Sample)

Source: https://docs.pkp.sfu.ca/dev/api/ojs/3.3.html

This is a sample JSON response for the GET /submissions endpoint, illustrating the structure of submission data returned by the API.

```json
{
  "itemsMax": 0,
  "items": [
    {
      "_href": "string",
      "contextId": 0,
      "currentPublicationId": 0,
      "dateLastActivity": "string",
      "dateSubmitted": "string",
      "id": 0,
      "lastModified": "string",
      "locale": "string",
      "publications": [
        {
          "_href": "http://example.com",
          "abstract": {
            "en_US": "Filename",
            "fr_CA": "Nom de fichier"
},
          "accessStatus": 0,
          "authors": [
            {
              "affiliation": {
                "en_US": "Filename",
                "fr_CA": "Nom de fichier"
},
              "biography": {
                "en_US": "Filename",
                "fr_CA": "Nom de fichier"
},
              "country": "string",
              "email": "string",
              "familyName": {
                "en_US": "Filename",
                "fr_CA": "Nom de fichier"
},
              "givenName": {
                "en_US": "Filename",
                "fr_CA": "Nom de fichier"
},
              "id": 0,
              "includeInBrowse": true,
              "orcid": "string",
              "preferredPublicName": {
                "en_US": "Filename",
                "fr_CA": "Nom de fichier"
},
              "publicationId": 0,
              "seq": 0,
              "submissionLocale": "string",
              "url": "string",
              "userGroupId": 0
}
],
          "authorsString": "string",
          "authorsStringShort": "string",
          "categoryIds": [
            0
],
          "citations": [
            "string"
],
          "citationsRaw": "string",
          "copyrightHolder": {
            "en_US": "Filename",
            "fr_CA": "Nom de fichier"
},
          "copyrightYear": 0,
          "coverImage": {
            "type": null,
            "properties": null,
            "en_US": {
              "dateUploaded": "string",
              "uploadName": "string",
              "altText": "string"
},
            "fr_CA": {
              "dateUploaded": "string",
              "uploadName": "string",
              "altText": "string"
}
},
          "coverage": {
            "en_US": "Filename",
            "fr_CA": "Nom de fichier"
},
          "datePublished": "string",
          "disciplines": [

```

--------------------------------

### Multilingual Field Example (Multiple Languages)

Source: https://docs.pkp.sfu.ca/dev/api/usage.html

Multilingual fields are returned as a JSON object with locale codes as keys. This example shows titles in English and Canadian French.

```json
{
	"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"
	},
	...
}
```

--------------------------------

### PHP Void Return Type Example

Source: https://docs.pkp.sfu.ca/dev/contributors

Demonstrates the use of the `void` return type hint for functions that do not return any value in PHP.

```php
class Submission
{
    public function recordDecision(): void
    {
        $this->record();
    }
}


```
Tokens:
Raw