Skip to content

Web API (Gallery)

Jump to bottom
Jason Bertsche edited this page Jun 9, 2024 · 15 revisions

API Version: v1.2.0

/api/public/version

  • Method: GET
  • Parameters: None
  • Response Type: text/plain
  • Description: Responds with the value of the current API version ("1.2.0" at the time of writing)
  • Error Conditions: None

/api/public/galleries/{{session-id}}/template-name

  • Method: GET
  • Parameters:
    • session-id (required): The name of the session whose template name is sought
  • Response Type: text/plain
  • Description: Responds with the name of template associated with the session with the name given by session-id
  • Error Conditions:
    • No session with the name given by {{session-id}} exists (HTTP 404)

/echo/{{param}}

  • Method: POST
  • Parameters:
    • param: The name of the parameter in this request that you want to have echoed
  • Response Type: text/plain
  • Description: Responds with the value of the parameter in the request whose name matches the value of param
  • Error Conditions:
    • There is no parameter whose name matches the value of param (HTTP 422)

/new-session/{{template-name}}

  • Method: POST
  • Parameters:
    • template-name (required): The name of the template that is intended to be used with this session
  • Response Type: text/plain
  • Description: Automatically generates a semi-random name (of form {{adjective}} {{animal}}) for a session. Starts a session with the generated name and responds with that name. Links the session to the template given by template, for future use.
  • Error Conditions: None

/new-session/{{template}}/{{session-id}}

  • Method: POST
  • Parameters:
    • template (required): The name of the template that is intended to be used with this session
    • session-id (required): The name of the session that this being created
    • gets-prescreened (required): A boolean of whether or not this gallery should be pre-screened by a moderator
    • token (required): The moderator's UUID
    • config: The starter configuration for this session as a file, optionally GZipped
  • Response Type: text/plain
  • Description: Initializes a session with the name given by session-id, configuring it for pre-screening if gets-prescreened is true, and requiring to receive the same value for token in future privileged operations upon the session. Links the session to the template given by template and the starter configuration given by config, for future use.
  • Error Conditions:
    • A session with that name already exists (HTTP 409)

/moderator-token

  • Method: GET
  • Parameters: None
  • Response Type: text/plain
  • Description: Responds with a UUID that can be used as an identifying token in future requests.
  • Error Conditions: None

/uploader-token

  • Method: GET
  • Parameters: None
  • Response Type: text/plain
  • Description: Responds with a UUID that can be used as an identifying token in future requests.
  • Error Conditions: None

/file-uploads

  • Method: POST
  • Parameters:
    • session-id (required): The name of the session that the item should be uploaded into (as received after POSTing to /new-session)
    • image (required): A base64-encoded image for the item as a file, optionally GZipped
    • token: A UUID that should get correlated with the client's submissions
    • metadata: Lightweight data
    • data (required): Heavyweight data as a file, optionally GZipped
  • Response Type: text/plain
  • Description: Stores the supplied information in the database for retrieval later (see /uploads/{{session-id}}/{{item-id}}). Responds with the name that is automatically generated for the uploaded item. Differs from /uploads only in that the data and image are files. If no token (or only a blank token) is provided, certain operations will be unavailable for the uploaded work (e.g. suppression).
  • Error Conditions:
    • A required parameter is missing (HTTP 422)

/starter-config/:session-id

  • Method: GET
  • Parameters:
    • session-id (required): The name of the session that containing the sought-after starter config
  • Response Type: text/plain
  • Description: Responds with the starter configuration text associated with the session with the name given by session-id
  • Error Conditions:
    • No session with the name given by {{session-id}} exists (HTTP 404)
    • No starter config has been stored for the session {{session-id}} (HTTP 404)

/uploads

  • Method: POST
  • Parameters:
    • session-id (required): The name of the session that the item should be uploaded into (as received after POSTing to /new-session)
    • image (required): A base64-encoded image for the item
    • token: A UUID that should get correlated with the client's submissions
    • metadata: Lightweight data
    • data (required): Heavyweight data
  • Response Type: text/plain
  • Description: Stores the supplied information in the database for retrieval later (see /uploads/{{session-id}}/{{item-id}}). Responds with the name that is automatically generated for the uploaded item. If no token (or only a blank token) is provided, certain operations will be unavailable for the uploaded work (e.g. suppression).
  • Error Conditions:
    • A required parameter is missing (HTTP 422)

/uploads/{{session-id}}/{{item-id}}

  • Method: GET
  • Parameters:
    • session-id: The name of the session that contains the item of interest (as received after POSTing to /new-session)
    • item-id: The name of the item to be retrieved (as received after POSTing to /uploads)
  • Response Type: text/plain
  • Description: Returns the value that was supplied for data when /uploads was POSTed to.
  • Error Conditions:
    • No item with name {{item-id}} is stored in the session {{session-id}} (HTTP 404)

/uploads/{{session-id}}/{{item-id}}/{{token}}

  • Method: GET
  • Parameters:
    • session-id: The name of the session that contains the item of interest (as received after POSTing to /new-session)
    • item-id: The name of the item to be retrieved (as received after POSTing to /uploads)
    • token: A UUID
  • Response Type: text/plain
  • Description: Returns the value that was supplied for data when /uploads was POSTed to (provided that you have permission to view it, as designated by token)
  • Error Conditions:
    • You are not authorized to download that (HTTP 401)
    • No item with name {{item-id}} is stored in the session {{session-id}} (HTTP 404)

/uploads/{{session-id}}/{{item-id}}/{{token}}

  • Method: DELETE
  • Parameters:
    • session-id: The name of the session that contains the item of interest (as received after POSTing to /new-session)
    • item-id: The name of the item to be suppressed (as received after POSTing to /uploads)
    • token: A UUID identifying the client as an owner or moderator of the item in question
  • Response Type: text/plain
  • Description: Marks the item as "suppressed" in all future invocations of /listings/
  • Error Conditions:
    • No token was given (HTTP 401)
    • No item with name {{item-id}} is stored in the session {{session-id}} (HTTP 404)
    • The supplied token did not match the item's token (HTTP 401)

/uploads/{{session-id}}/{{item-id}}/{{token}}/approve

  • Method: POST
  • Parameters:
    • session-id: The name of the session that contains the item of interest (as received after POSTing to /new-session)
    • item-id: The name of the item to be approved (as received after POSTing to /uploads)
    • token: A UUID identifying the client as a moderator of the item in question
  • Response Type: text/plain
  • Description: Marks an item in a "pre-screened" gallery as approved for viewing by non-moderators in all future invocations of /listings/
  • Error Conditions:
    • No token was given (HTTP 401)
    • No item with name {{item-id}} is stored in the session {{session-id}} (HTTP 404)
    • The supplied token did not match the item's token (HTTP 401)

/uploads/{{session-id}}/{{item-id}}/{{token}}/reject

  • Method: POST
  • Parameters:
    • session-id: The name of the session that contains the item of interest (as received after POSTing to /new-session)
    • item-id: The name of the item to be rejected (as received after POSTing to /uploads)
    • token: A UUID identifying the client as a moderator of the item in question
  • Response Type: text/plain
  • Description: Marks an item in a "pre-screened" gallery as rejected; it will be invisible to everyone in all queries, going forward
  • Error Conditions:
    • No token was given (HTTP 401)
    • No item with name {{item-id}} is stored in the session {{session-id}} (HTTP 404)
    • The supplied token did not match the item's token (HTTP 401)

/comments

  • Method: POST
  • Parameters:
    • session-id (required): The name of the session that contains the item of interest (as received after POSTing to /new-session)
    • item-id (required): The name of the item for which to upload a comment (as received after POSTing to /uploads)
    • comment (required): The comment to be posted
    • author (required): The name of the author of the comment
    • parent: The UUID of the parent comment (if any) (as found in after GETting from /comments/{{session-id}}/{{item-id}})
  • Response Type: text/plain
  • Description: Stores the supplied information in the database for retrieval later (see /comments/{{session-id}}/{{item-id}}). Responds with empty text.
  • Error Conditions:
    • A required parameter is missing (HTTP 422)

/comments/{{session-id}}/{{item-id}}

  • Method: GET
  • Parameters:
    • session-id: The name of the session that contains the item of interest (as received after POSTing to /new-session)
    • item-id: The name of the item for which comments should be retrieved (as received after POSTing to /uploads)
  • Response Type: application/json
  • Description: Returns a JSON array of the comments, where each comment has the form: { uuid: <string of a UUID>, comment: <string>, author: <string>, parent: <string|undefined>, time: <number of POSIX time milliseconds> }.
  • Error Conditions: None

/listings/{{session-id}}

  • Method: GET
  • Parameters:
    • session-id: The name of the session of interest (as received after POSTing to /new-session)
  • Response Type: application/json
  • Description: Returns a JSON array of items in the format { subName: <name of the submitted item>, isSuppressed: <boolean of whether or not this item has been suppressed> }
  • Error Conditions: None

/listings/{{session-id}}/exists

  • Method: GET
  • Parameters:
    • session-id: The name of the session of interest (as received after POSTing to /new-session)
  • Response Type: application/json
  • Description: Returns true if that session exists, and false if it does not
  • Error Conditions: None

/mod-listings/{{session-id}}/{{token}}

  • Method: GET
  • Parameters:
    • session-id: The name of the session of interest (as received after POSTing to /new-session)
    • token: A UUID identifying the client as a moderator of the session
  • Response Type: application/json
  • Description: Returns a JSON array of submission names
  • Error Conditions:
    • You are not authorized to read those submissions (HTTP 401)

/gallery-listings/{{token}}

  • Method: GET
  • Parameters:
    • token (required): A UUID
  • Response Type: application/json
  • Description: Returns a JSON array of all galleries that token is registered as a moderator of, with each gallery taking the form { galleryName: <string>, template: <string, name of gallery type>, description: <string>, isPrescreened: <boolean>, numWaiting: <number of entries awaiting pre-screening>, numApproved: <number of publicly-visible entries>, creationTime: <POSIX timestamp of when this gallery was made>, lastSubTime: <POSIX timestamp of when this gallery's last submission came in> }
  • Error Conditions: None

/data-lite

  • Method: POST
  • Parameters:
    • session-id (required): The name of the session containing the items of interest (as received after POSTing to /new-session)
    • names (required): A JSON array of the names of the items for which the lite data should be retrieved (as received after each was POSTed to /uploads)
  • Response Type: application/json
  • Description: Returns a JSON array of the items, where each item has the form: { uploadName: <string of 'item-id'>, base64Image: <string of uploaded 'image'>, isOwner: false, canModerate: false, metadata: <string of uploaded 'metadata'> }
  • Error Conditions:
    • A required parameter is missing (HTTP 422)
    • names is not a valid JSON array (HTTP 422)

/data-lite/{{token}}

  • Method: POST
  • Parameters:
    • session-id (required): The name of the session containing the items of interest (as received after POSTing to /new-session)
    • names (required): A JSON array of the names of the items for which the lite data should be retrieved (as received after each was POSTed to /uploads)
    • token (required): A UUID identifying the client
  • Response Type: application/json
  • Description: Returns a JSON array of the items, where each item has the form: { uploadName: <string of 'item-id'>, base64Image: <string of uploaded 'image'>, isOwner: <boolean of whether or not the token was non-empty and matched the token that the requested item was uploaded with>, canModerate: <boolean of whether or not the token matched that of the owner of the gallery, or true if isOwner is true>, metadata: <string of uploaded 'metadata'> }
  • Error Conditions:
    • A required parameter is missing (HTTP 422)
    • names is not a valid JSON array (HTTP 422)

Clone this wiki locally