[ Overview ] [ Sessions ] [ Entities ] [ Special Namespaces ] [ Other Types ] [ Hints ]

Protocol Overview

The WCO-API is a new way to access and edit the state of WebCheckout via HTTP in a RESTful style using JSON.

Latter pages in this document will assume you are familiar with the former sections. Please do read through at least the first 4 sections in their entirety.

It is assumed that the reader has some knowledge of JSON and RESTful APIs in general. This document may include examples, but it is not intended to be a complete how-to guide or an introduction to RESTful APIs.

There is not always complete agreement on what is and is not RESTy. We have no intention of wading into that debate. Our API is being used to progressively modernize our application and as such, during its development, is subject to the needs of a living breathing application and user base. In short, those places where we have strayed from the REST paradigm are likely to have been caused by the need to follow design patterns and use cases that have developed over many years.

Documentation Conventions

Let's get some conventions out of the way. Throughout this document, when ever we need to format a post to the API along with the posted data is formatted as so...

POST URL

	  {
	      "hello": "world"
	  }

Similarly, the status code and the JSON returned by the API is formatted thus...

HTTP 200

	  {
	      "json": "awesome"
	  }

A Note About Case

The language of our core, ANSI Common Lisp, is historically a case insensitive language. Common lisp identifiers are written with hyphens separating words (for example "my-identifier"). On the other hand JavaScript, the anticipated client of the API, is case sensitive, reserving the '-' character for subtraction, and so uses lowerCamelCase ("myIdentifier") for non-quoted symbols. JSON keys are quoted strings, so they can go either way. Don't get me started on HTML element tags and Angular directives.

We opted to pretend in the API that the lisp 'hyphenated case' doesn't exist since it tends to perplex those more familiar with JavaScript. That said, While reading these documents you may find either of the cases or, if we are really trying to trip you up, we may actually use multiple words. So allocationItem, allocation-item, and allocation item may all refer to the same thing. We will try to keep this to a minimum.

As we normalize these docs we are going to err on the side of lowerCamelCase. Sorry in advance for any confusion

Namespaces

Namespaces are the highest level separation of REST operations. All operations in the API exist under a namespace, most namespaces correspond to a specific Framework Entity (such as a person or an allocation) However, some special namespaces exist that have their own conventions.

Entities are complex objects in the WebCheckout core and are handled in their own section.

URIs

WebCheckout REST API URIs are formatted as follows.

rest/<namespace>/<optional command or object identifier>

HTTP Encoding

All Messages to and from the REST API should be encoded with the Content-Type "application/json; charset=UTF-8".

All arguments and data are passed to and from the REST API in the HTTP Request and Response payload as UTF-8 Formatted JSON.

HTTP Methods

All operations to the WebCheckout REST API use the HTTP POST operation.

API Response Format

All responses from the REST API will be a JSON object with at least nine values.

apiVersion
uri
session
status
notifications
alert
payload
sessionToken
sessionid

API Version

The API Version is intended to communicate major changes in the API to third party users. Currently the API is version 2.0.

New in 2.0

Session ID based authentication has been phased out. Bearer Auth token based auth is now the only method available to API consumers. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization

Session The session value identifies the WebCheckout framework session this JSON message was created for. Session information may be used by the user to cache certain information and will remain stable through the life of the session. It will be null if the user has not yet authenticated. Status The status of an API response will be one of seven possible values:

ok
The request processed correctly
error
There was an error in the REST server or the Framework
unauthenticated
The session is not authenticated
noOrganization
The session organization must be set to perform this operation
noCheckoutCenter
The session checkout center must be set to perform this operation
authorizationRequired
The consumer must provide additional authentication to complete the previous operation.
authorizationFailed
The consumers attempt to provide additional authorization information failed.

Notifications null, or an array of one or more notification messages intended to provide extra information to the user.

	[
	    {
                "message": "Everything is coming up Millhouse", 
                "type": "success"
	    }
        ]

type will be one of the following:

success
warning
error

Payload The payload is dependent on the API Operation and can range from null to deeply nested context-sensitive data. Session Token The Session Token is a unique string used for Authentication and Authorization. It is also known as a Bearer token. Currently it can be POSTED in the Authorization header of an API HTTP request to authenticate said request. More on that here. Sessionid The sessionid is a token identifying a unique session to the API. It may or may not be used depending on the style of session management in use. It is considered the legacy way to manage session authentication. More on that in the API v1.1 documentation here: sessions.

HTTP Return Codes

All successful REST API calls will return the HTTP response code 200. Only extra-protocol errors use HTTP response codes.

There are some circumstances when the code is non-200

400 Bad Request A request for a non-existing method

POST /rest/person/noSuchCommand HTTP/1.1

      {
        "headers": {
          "Authorization": "Bearer eyJ0eXBlIjogInNlc3Npb24iLCAidmFsdWUiOiAiYjJmODU5MGMtNWQwOS00NDBkLWFhNjgtNTNkZDY0ZmM2NjFjIn0="
        }
      }

HTTP 400

      {
        "apiVersion": "2.0",
        "uri": "/rest/person/noSuchCommand",
        "session": {
          "id": "S-78064",
          "agent": {
            "_class": "person",
            "oid": 533,
            "name": "Super",
            "avatar": null,
            "lastName": null,
            "otherName": "",
            "firstName": "Super",
            "userid": "adminuser"
          },
          "checkoutCenter": null,
          "organization": null,
          "focusAllocation": null,
          "editingAllocations": null,
          "transientDocuments": null,
          "resetTimeout": false,
          "resetApproved": false
        },
        "status": "error",
        "notifications": null,
        "alert": null,
        "payload": {
          "message": "Requested command NO-SUCH-COMMAND was not found in namespace PERSON",
          "class": "REST-SERVER:FRAMEWORK-COMMAND-NOT-FOUND"
        },
        "sessionToken": "eyJ0eXBlIjogInNlc3Npb24iLCAidmFsdWUiOiAiYjJmODU5MGMtNWQwOS00NDBkLWFhNjgtNTNkZDY0ZmM2NjFjIn0=",
        "sessionid": "b2f8590c-5d09-440d-aa68-53dd64fc661c"
      }

404 Not Found A request for a resource in a namespace that does not exist

POST /rest/noSuchNameSpace/noSuchCommand HTTP/1.1

      {
        "headers": {
          "Authorization": "Bearer eyJ0eXBlIjogInNlc3Npb24iLCAidmFsdWUiOiAiYjJmODU5MGMtNWQwOS00NDBkLWFhNjgtNTNkZDY0ZmM2NjFjIn0="
        }
      }

HTTP 404

      {
        "apiVersion": "2.0",
        "uri": "/rest/noSuchNameSpace/noSuchCommand",
        "session": {
          "id": "S-78064",
          "agent": {
            "_class": "person",
            "oid": 533,
            "name": "Super",
            "avatar": null,
            "lastName": null,
            "otherName": "",
            "firstName": "Super",
            "userid": "adminuser"
          },
          "checkoutCenter": null,
          "organization": null,
          "focusAllocation": null,
          "editingAllocations": null,
          "transientDocuments": null,
          "resetTimeout": false,
          "resetApproved": false
        },
        "status": "error",
        "notifications": null,
        "alert": null,
        "payload": {
          "message": "Requested namespace NO-SUCH-NAME-SPACE was not found",
          "class": "REST-SERVER:NAMESPACE-NOT-FOUND"
        },
        "sessionToken": "eyJ0eXBlIjogInNlc3Npb24iLCAidmFsdWUiOiAiYjJmODU5MGMtNWQwOS00NDBkLWFhNjgtNTNkZDY0ZmM2NjFjIn0=",
        "sessionid": "b2f8590c-5d09-440d-aa68-53dd64fc661c"
      }

405 Method Not Allowed Any use of an HTTP Request method other than POST

GET /rest/session/currentSession HTTP/1.1

      {
        "headers": {
          "Authorization": "Bearer eyJ0eXBlIjogInNlc3Npb24iLCAidmFsdWUiOiAiYjJmODU5MGMtNWQwOS00NDBkLWFhNjgtNTNkZDY0ZmM2NjFjIn0="
        }
      }

HTTP 405

      {
        "apiVersion": "2.0",
        "uri": "/rest/session/currentSession",
        "session": null,
        "status": "error",
        "notifications": null,
        "alert": null,
        "payload": {
          "message": "All WCO API commands require the HTTP POST method",
          "class": "REST-SERVER:METHOD-NOT-ALLOWED"
        }
      }

500 Internal Server Error An uncaught fatal error in the application. The equivalent of the gray screen in WebCheckout.

POST /rest/session/testError HTTP/1.1

      {
        "headers": {
          "Authorization": "Bearer eyJ0eXBlIjogInNlc3Npb24iLCAidmFsdWUiOiAiYjJmODU5MGMtNWQwOS00NDBkLWFhNjgtNTNkZDY0ZmM2NjFjIn0="
        }
      }

HTTP 500

      {
        "apiVersion": "2.0",
        "uri": "/rest/session/testError",
        "session": {
          "id": "S-78064",
          "agent": {
            "_class": "person",
            "oid": 533,
            "name": "Super",
            "avatar": null,
            "lastName": null,
            "otherName": "",
            "firstName": "Super",
            "userid": "adminuser"
          },
          "checkoutCenter": null,
          "organization": null,
          "focusAllocation": null,
          "editingAllocations": null,
          "transientDocuments": null,
          "resetTimeout": false,
          "resetApproved": false
        },
        "status": "error",
        "notifications": null,
        "alert": null,
        "payload": {
          "message": "TEST ERROR",
          "class": "COMMON-LISP:SIMPLE-ERROR"
        },
        "sessionToken": "eyJ0eXBlIjogInNlc3Npb24iLCAidmFsdWUiOiAiYjJmODU5MGMtNWQwOS00NDBkLWFhNjgtNTNkZDY0ZmM2NjFjIn0=",
        "sessionid": "b2f8590c-5d09-440d-aa68-53dd64fc661c"
      }