What is this endpoint for?
Activities are the object definition for a student exercise within one of the Empirical Platform apps. (e.g. Quill Grammar, Quill Writer, etc). The endpoint supports GET, POST and PATCH methods, to retrieve, update (edit) and create new activities respectively.
How is it structured?
The structure is reasonably straightforward, and can be described in these key ways:
- Activity General Data
- Activity Serialized Data
- Common Core / Lesson Structure Context
- Response/Request API Metadata
The Activity most importantly contains the name and description attributes, which are used to identify the activity within the Empirical dashboards.
The uid attribute is generated by Empirical Core, and is used to identify the object within the API. It's simply a UUID style reference used to help provide a static, immutable permanent reference for any object requested over the API.
The data attribute is a hash, storing key value pairs of data that your app requires. It's unvalidated and free-form, allowing you to use it as required. You should serialize your keys, as there is no serialization performed on the API side as of yet. We recommend serializing in JSON.
Activities all belong to a classification, which is essentially a descriptor of the app installed. It has a name, key and more importantly module_url and form_url which are used for the iframes which host the apps. The classifications are generated directly in the API, and do not have an endpoint to reference them.
Activities also belong to a topic, which describes the direct grouping for the activity requested. They, in turn, belong to sections, which belongs to a workbook. This refers to the way the activity is contextualized by the Common Core standard.
Finally, each request is accompanied by three keys within a hash called metadata. They are, status, message and, where necessary, errors.
Status contains either 'success', 'failure', 'not_found' or 'unknown' symbols, and can be used to quickly verify a request. The HTTP status code is also used to identify a more detailed sense of progress.
Message is a longer sentence to describe the status, and errors will refer to ActiveRecord error data.