diff --git a/README.md b/README.md index 968105381..782041b6d 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,9 @@ Extensive online help has more on configuring and using HotCRP. See also: * [The HotCRP development manual](./devel/manual/index.md) to learn about advanced configuration, software internals, and developing extensions. -* [The OpenAPI specification](./devel/openapi.json) for API information. +* [The OpenAPI specification](https://hotcrp.com/devel/api/) for API + information (local specification in + [devel/openapi.json](./devel/openapi.json)). Prerequisites diff --git a/devel/apidoc/documents.md b/devel/apidoc/documents.md index ae3b9d409..244192f81 100644 --- a/devel/apidoc/documents.md +++ b/devel/apidoc/documents.md @@ -52,5 +52,6 @@ store. * response size nonnegative_integer * response ranges [offset_range] * response hash string +* response crc32 string * response server_progress_loaded integer * response server_progress_max integer diff --git a/devel/apidoc/index.md b/devel/apidoc/index.md index dd02463e7..9bed44d87 100644 --- a/devel/apidoc/index.md +++ b/devel/apidoc/index.md @@ -13,18 +13,17 @@ requests](https://github.com/kohler/hotcrp/pulls). ## Overview -HotCRP parameters are generally provided using [form +API calls use paths under `api`. For instance, to call the `paper` endpoint on +a server at `https://example.hotcrp.org/funconf25`, you might use a URL like +`https://example.hotcrp.org/funconf25/api/paper?p=1`. + +Most parameters are provided using [form encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST), either in query strings or in the request body. Some parameters are formatted -as JSON. Complex requests generally use structured keys, such as -`named_search/1/q`. Use `multipart/form-data` -for requests that include uploaded files. - -The common `p` parameter defines a submission ID. It can appear either in the -query string or immediately following `api/` in the query path: -`api/comment?p=1` and `api/1/comment` are the same API call. `p` is a positive -decimal integer, but some API calls accept `p=new` when defining a new -submission. +as JSON. Some complex requests use structured keys, such as +`named_search/1/q`. Use `multipart/form-data` for requests that include +uploaded files. Since servers limit upload size, you may need to use the +upload API to upload a large file before processing it with another call. Responses are formatted as JSON. Every response has an `ok` property; `ok` is `true` if the request succeeded and `false` otherwise. Messages about the @@ -36,10 +35,17 @@ deleting a comment uses a `delete=1` parameter for a `POST` request, rather than a `DELETE` request. +### Common parameters + +The `p` parameter defines a submission ID. It can appear either in the query +string or immediately following `api/` in the query path: `api/comment?p=1` +and `api/1/comment` are the same API call. `p` is a positive decimal integer, +but some API calls accept `p=new` when defining a new submission. + + ### Authentication External applications should authenticate to HotCRP’s API using bearer tokens -(an `Authorization: bearer` HTTP header). Obtain an API token using Account -settings > Developer. - -HotCRP Javascript makes API calls using session cookies for authentication. +(an `Authorization: bearer` HTTP header). Obtain API tokens using Account +settings > Developer. HotCRP Javascript makes API calls using session cookies +for authentication. diff --git a/devel/apidoc/openapi-base.json b/devel/apidoc/openapi-base.json index f7d64aa8a..13152b8f0 100644 --- a/devel/apidoc/openapi-base.json +++ b/devel/apidoc/openapi-base.json @@ -1,6 +1,17 @@ { "openapi": "3.1.0", "info": {}, + "servers": [ + { + "url": "https://{site}.hotcrp.com/api", + "description": "HotCRP.com site server", + "variables": { + "site": { + "default": "demo" + } + } + } + ], "paths": {}, "components": { "parameters": { diff --git a/devel/apidoc/submissions.md b/devel/apidoc/submissions.md index 44908be98..5ba232604 100644 --- a/devel/apidoc/submissions.md +++ b/devel/apidoc/submissions.md @@ -9,15 +9,14 @@ These endpoints query and modify HotCRP submissions. This endpoint retrieves JSON-formatted information about a submission. All visible information about submission fields, tags, and overall status are -returned in as the response’s `paper` property. Error messages—for instance, -about permission errors or nonexistent submissions—are returned in -`message_list`. +returned in the `paper` response property, which defines a submission object. +Error messages—for instance, about permission errors or nonexistent +submissions—are returned in `message_list`. -The returned `paper` property is a submission object. Submission objects are -formatted based on the submission form. Every paper object has an `object` -property set to `"paper"`, a `pid`, and a `status`. Other properties are -provided based on which submission fields exist and whether the accessing user -can see them. +Submission objects are formatted based on the submission form. They have an +`object` property set to `"paper"`, a `pid`, and a `status`. Other properties +are provided based on which submission fields exist and whether the accessing +user can see them. * param forceShow boolean: False to not override administrator conflict * response ?paper paper @@ -31,22 +30,27 @@ This endpoint modifies the submission specified by the `p` parameter. Setting `p=new` will create a new submission; the response will contain the chosen submission ID. -Modifications are specified using a JSON object. There are three ways to -provide that JSON, depending on the content-type of the request: +The modification may be specified: -1. As a JSON request body with content-type `application/json`. -2. In a ZIP archive request body with content-type `application/zip`, as a - file named `data.json`. -3. As a parameter named `json` in a normal `application/x-www-form-urlencoded` - or `multipart/form-data` body. +1. As a JSON request body (when the request body has content-type + `application/json`). +2. As a ZIP archive (when the request body has content-type + `application/zip`). The archive must contain a file named `data.json`; it + may contain other files too. +3. As a JSON-formatted request parameter named `json` (when the request body + has content-type `application/x-www-form-urlencoded` or + `multipart/form-data`). +4. As a previously-uploaded JSON or ZIP file, represented by a upload token in + the `upload` parameter. -However it is provided, the JSON must define an object interpretable as a -submission (or a subset of a submission). The properties of this object define -the modifications to be applied to the submission. +In all of these, the modification is defined by a JSON submission object. The +properties of this object define the modifications applied to the submission. +The object need not specify all submission properties; absent properties +remain unchanged. -The `p` parameter is optional; if unset, HotCRP uses the `pid` from the -supplied JSON. If the `p` parameter and the JSON `pid` property are both -present, then they must match. +The `p` request parameter is optional. If it is unset, HotCRP uses the `pid` +from the supplied JSON. If both the `p` parameter and the JSON `pid` property +are present, however, then they must match. To test a modification, supply a `dry_run=1` parameter. This will test the uploaded JSON but make no changes to the database. @@ -112,6 +116,7 @@ existing submission, set the JSON’s `status`.`if_unmodified_since` to `0`. * param add_topics boolean: True automatically adds topics from input papers (administrators only) * param notify boolean: False does not notify contacts of changes (administrators only) * param ?json string +* param ?upload upload_token: Defines upload token for large input file * response ?dry_run boolean: True for `dry_run` requests * response ?paper paper: JSON version of modified paper * response ?+change_list [string]: List of changed fields @@ -130,7 +135,7 @@ too. The response property `papers` is an array of matching submission objects. Since searches silently filter out non-viewable submissions, `/papers?q=1010` and `/paper?p=1010` can return different error messages. The `/paper` request might return an error like `Submission #1010 does not exist` or `You aren’t -allowed to view submission #10110`, whereas the `/papers` request will return +allowed to view submission #1010`, whereas the `/papers` request will return no errors. To obtain warnings for missing submissions that were explicitly listed in a query, supply a `warn_missing=1` parameter. @@ -166,7 +171,8 @@ relevant submission in the input JSON. * param disable_users boolean: True disables any newly-created users (administrators only) * param add_topics boolean: True automatically adds topics from input papers (administrators only) * param notify boolean: False does not notify contacts of changes (administrators only) -* param json string +* param ?json string +* param ?upload upload_token: Defines upload token for large input file * param ?q search_string: Search query for match requests * param ?t search_collection: Collection to search; defaults to `viewable` * response ?dry_run boolean: True for `dry_run` requests diff --git a/devel/openapi.json b/devel/openapi.json index ac8d9b4c7..6feb2247f 100644 --- a/devel/openapi.json +++ b/devel/openapi.json @@ -2,15 +2,26 @@ "openapi": "3.1.0", "info": { "title": "HotCRP REST API", - "version": "2024-12-09:74fb3c4fc", + "version": "2025-03-02:e11c872c9", "summary": "HotCRP conference management software API", - "description": "[HotCRP](https://github.com/kohler/hotcrp) is conference review software. It\nis open source; a supported version runs on [hotcrp.com](https://hotcrp.com/).\nThis documentation is for the HotCRP REST-like API.\n\nTo request documentation for an API method, please open a [GitHub\nissue](https://github.com/kohler/hotcrp/issues). We also welcome [pull\nrequests](https://github.com/kohler/hotcrp/pulls).\n\n\n## Overview\n\nHotCRP parameters are generally provided using [form\nencoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST),\neither in query strings or in the request body. Some parameters are formatted\nas JSON. Complex requests generally use structured keys, such as\n`named_search/1/q`. Use `multipart/form-data`\nfor requests that include uploaded files.\n\nThe common `p` parameter defines a submission ID. It can appear either in the\nquery string or immediately following `api/` in the query path:\n`api/comment?p=1` and `api/1/comment` are the same API call. `p` is a positive\ndecimal integer, but some API calls accept `p=new` when defining a new\nsubmission.\n\nResponses are formatted as JSON. Every response has an `ok` property; `ok` is\n`true` if the request succeeded and `false` otherwise. Messages about the\nrequest, if any, are expressed in a `message_list` property.\n\nThe `GET` method is used to retrieve information and the `POST` method to\nmodify information. Other methods are generally not used; for instance,\ndeleting a comment uses a `delete=1` parameter for a `POST` request, rather\nthan a `DELETE` request.\n\n\n### Authentication\n\nExternal applications should authenticate to HotCRP’s API using bearer tokens\n(an `Authorization: bearer` HTTP header). Obtain an API token using Account\nsettings > Developer.\n\nHotCRP Javascript makes API calls using session cookies for authentication.\n" + "description": "[HotCRP](https://github.com/kohler/hotcrp) is conference review software. It\nis open source; a supported version runs on [hotcrp.com](https://hotcrp.com/).\nThis documentation is for the HotCRP REST-like API.\n\nTo request documentation for an API method, please open a [GitHub\nissue](https://github.com/kohler/hotcrp/issues). We also welcome [pull\nrequests](https://github.com/kohler/hotcrp/pulls).\n\n\n## Overview\n\nAPI calls use paths under `api`. For instance, to call the `paper` endpoint on\na server at `https://example.hotcrp.org/funconf25`, you might use a URL like\n`https://example.hotcrp.org/funconf25/api/paper?p=1`.\n\nMost parameters are provided using [form\nencoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST),\neither in query strings or in the request body. Some parameters are formatted\nas JSON. Some complex requests use structured keys, such as\n`named_search/1/q`. Use `multipart/form-data` for requests that include\nuploaded files. Since servers limit upload size, you may need to use the\nupload API to upload a large file before processing it with another call.\n\nResponses are formatted as JSON. Every response has an `ok` property; `ok` is\n`true` if the request succeeded and `false` otherwise. Messages about the\nrequest, if any, are expressed in a `message_list` property.\n\nThe `GET` method is used to retrieve information and the `POST` method to\nmodify information. Other methods are generally not used; for instance,\ndeleting a comment uses a `delete=1` parameter for a `POST` request, rather\nthan a `DELETE` request.\n\n\n### Common parameters\n\nThe `p` parameter defines a submission ID. It can appear either in the query\nstring or immediately following `api/` in the query path: `api/comment?p=1`\nand `api/1/comment` are the same API call. `p` is a positive decimal integer,\nbut some API calls accept `p=new` when defining a new submission.\n\n\n### Authentication\n\nExternal applications should authenticate to HotCRP’s API using bearer tokens\n(an `Authorization: bearer` HTTP header). Obtain API tokens using Account\nsettings > Developer. HotCRP Javascript makes API calls using session cookies\nfor authentication.\n" }, + "servers": [ + { + "url": "https://{site}.hotcrp.com/api", + "description": "HotCRP.com site server", + "variables": { + "site": { + "default": "demo" + } + } + } + ], "paths": { "/paper": { "get": { "summary": "Retrieve submission", - "description": "This endpoint retrieves JSON-formatted information about a submission. All\nvisible information about submission fields, tags, and overall status are\nreturned in as the response’s `paper` property. Error messages—for instance,\nabout permission errors or nonexistent submissions—are returned in\n`message_list`.\n\nThe returned `paper` property is a submission object. Submission objects are\nformatted based on the submission form. Every paper object has an `object`\nproperty set to `\"paper\"`, a `pid`, and a `status`. Other properties are\nprovided based on which submission fields exist and whether the accessing user\ncan see them.\n", + "description": "This endpoint retrieves JSON-formatted information about a submission. All\nvisible information about submission fields, tags, and overall status are\nreturned in the `paper` response property, which defines a submission object.\nError messages—for instance, about permission errors or nonexistent\nsubmissions—are returned in `message_list`.\n\nSubmission objects are formatted based on the submission form. They have an\n`object` property set to `\"paper\"`, a `pid`, and a `status`. Other properties\nare provided based on which submission fields exist and whether the accessing\nuser can see them.\n", "tags": [ "Submissions" ], @@ -65,7 +76,7 @@ }, "post": { "summary": "Create or modify submission", - "description": "This endpoint modifies the submission specified by the `p` parameter. Setting\n`p=new` will create a new submission; the response will contain the chosen\nsubmission ID.\n\nModifications are specified using a JSON object. There are three ways to\nprovide that JSON, depending on the content-type of the request:\n\n1. As a JSON request body with content-type `application/json`.\n2. In a ZIP archive request body with content-type `application/zip`, as a\n file named `data.json`.\n3. As a parameter named `json` in a normal `application/x-www-form-urlencoded`\n or `multipart/form-data` body.\n\nHowever it is provided, the JSON must define an object interpretable as a\nsubmission (or a subset of a submission). The properties of this object define\nthe modifications to be applied to the submission.\n\nThe `p` parameter is optional; if unset, HotCRP uses the `pid` from the\nsupplied JSON. If the `p` parameter and the JSON `pid` property are both\npresent, then they must match.\n\nTo test a modification, supply a `dry_run=1` parameter. This will test the\nuploaded JSON but make no changes to the database.\n\n\n### ZIP and form uploads\n\nA ZIP upload should contain a file named `data.json` (`PREFIX-data.json` is\nalso acceptable). This file’s content is parsed as JSON. Submission fields in\nthe JSON can refer to other files in the ZIP. For instance, this shell session\nuploads a new submission with content `paper.pdf`:\n\n```\n$ cat data.json\n{\n\t\"object\": \"paper\",\n\t\"pid\": \"new\",\n\t\"title\": \"Aught: A Methodology for the Visualization of Scheme\",\n\t\"authors\": [{\"name\": \"Nevaeh Gomez\", \"email\": \"ngomez@example.edu\"}],\n\t\"submission\": {\"content_file\": \"paper.pdf\"},\n\t\"status\": \"submitted\"\n}\n$ zip upload.zip data.json paper.pdf\n$ curl -H \"Authorization: bearer hct_XXX\" --data-binary @upload.zip -H \"Content-Type: application/zip\" SITEURL/api/paper\n```\n\nThis shell session does the same, but using `multipart/form-data`.\n\n```\n$ curl -H \"Authorization: bearer hct_XXX\" -F \"json=