Permalink
Fetching contributors…
Cannot retrieve contributors at this time
149 lines (127 sloc) 6.24 KB

Wall API

Common errors

The following errors are not listed under each API since they're pretty common.

  • logged-out - No session was available for an API that requires a login
  • no-auth - Authorization check failed (e.g. trying to change someone else's wall)
  • server-error - Something unexpected went wrong with the server
  • bad-request - Required parameters to the function were missing or of the wrong format

Errors are specified in the error_key element of the returned JSON array. Sometimes there is a error_detail element too and occasionally it contains some useful information.

JSON API

/api/walls[POST]
Create new wall [session required].

Parameters:

  • name (Name of wall) [Required]
  • design (ID of design to use) [Required]

Returns: the created wall (same parameters as when getting wall)

Errors:

  • TBD
/api/walls/<wall-id>[GET]
Get details of the specified wall [auth required].

Returns: the specified wall with the following parameters.

  • wallId - The unique ID of the wall
  • name - The name of the wall
  • wallUrl - The URL of the wall running the latest session
  • editorUrl - The URL of the editor tied to this wall
  • editorUrlShort - A shortened version of editorUrl. null if no shortening service was available.
  • duration - The number of milliseconds required to complete a single iteration of the wall. Will be null if the design default duration is used (as specified by defaultDuration).
  • defaultDuration - The default number of milliseconds required to complete a single of the wall as specified by the design.
  • ownerEmail - The email address of the person who is the owner of the wall.
  • designId - The unique identified of the design in use for this wall.
  • thumbnail - A thumbnail representation of the wall.
  • status - Either running or finished depending on if this wall has an active session or not.
  • latestSession - The most recently created session. Includes the following information.
  • sessionId - The identifier of the session
  • start - The time when the session was started in the format "Y-m-d H:i:s"
  • end - The time when the session was ended in the format "Y-m-d H:i:s" or null if the session has not yet ended.

Errors:

  • not-found - Wall ID wasn't located
  • TBD
/api/walls/<wall-id>[PUT]
Updates the specified wall.

Parameters:

  • key → value

(You can provide multiple keys and values but then when you get an error you won't know which key caused it so it's not very useful at the moment.)

Accepted keys:

  • name → Update wall name
    • Returns name (the wall sanitized wall name--basically trims whitespace)
    • Specific errors: duplicate-name (there is already another wall with that name)
  • urlPath → Update path component of URL
    • Returns wallUrl (the full URL of the wall--URL encoded), editorUrl (the full URL of the editor--URL encoded), and, if a URL shortening service is available editorUrlShort (the shortened editor URL)
    • Specific errors: bad-path (the path is not acceptable: is empty, has slashes, dots etc.), duplicate-path (there is already another wall with that path)
  • designId → Update the design of the wall
    • Returns designId (the provided design ID), thumbnail (an updated thumbnail for the wall), defaultDuration (the duration specified for the update design)
    • Specific errors: bad-design (the design wasn't found)
  • duration → Update the number of milliseconds taken to complete one cycle of the wall
    • Accepts either an integer number of milliseconds of null to mean, "Reset back to the default duration for this design"
    • Returns duration and defaultDuration

Errors:

  • not-found - The specified wall doesn't seem to exist
  • readonly-field - The key is recognized, but you can't change that field
  • unknown-field - The key isn't recognized
/api/walls/<wall-id>/sessions[GET]
Gets the list of sessions for the wall [auth currently required].

Returns: an array of sessions ordered by sessionId with the following information for each session:

  • sessionId - The identifier of the session
  • start - The time when the session was started in the format "Y-m-d H:i:s"
  • end - The time when the session was ended in the format "Y-m-d H:i:s" or null if the session has not yet ended.
/api/walls/<wall-id>/sessions[POST]
Closes the most recent session if it is open and creates a new session [auth required].

Parameters:

  • sessionId (The ID of the latest session) [Required]

Returns: details of the latest session using the same format as each of the elements returned in the list of sessions.

Errors:

  • parallel-change - The provided sessionId did not match the ID of the latest session. The error_detail in this case is filled in with the latest session.
/api/walls/<wall-id>/sessions/<session-id>[PUT]
Closes the current session [auth required].

Returns: details of the latest session using the same format as each of the elements returned in the list of sessions.

Errors:

  • parallel-change - The session-id specified in the URL did not match the ID of the latest session or that sesssion has already been closed. The error_detail in this case is filled in with the latest session.