API Documentation

Owned by Alexander Leader
Last updated: Dec 19, 2016 by Jason Elwood
4 min read

This page documents the various APIs that are available through Student Success Plan.

Person Data

Security Data

Reference Data

Form Data

General Notes

API result limits

All API calls have an upper limit to the number of results returned. This usually only applies to the "Get All" and similar methods, especially the ones that have start and limit parameters. Though it can apply to any method that returns multiple results directly or somewhere nested within the data structure. If the limit parameter is ever more than the hard-coded upper limit for this parameter, then the API will still only return up to the upper limit number of results.

If you need to retrieve more results than the maximum upper limit, multiple calls to the API method will be required. Increase the start parameter as appropriate with each call until you have retrieved all the results necessary.

The exact upper limit may change, but currently it is 1000.

Also, If the limit parameter is not specified for these types of API calls, a default will be used. The default limit value may change, but currently it is 100. If you would like to see more results per API call to these types of methods, send an explicit limit parameter, as long as it is still below the maximum upper limit as discussed above.

ObjectStatus

ObjectStatus is applied to almost all entities and services in the system. A particular data item can be Active or Inactive.

Data marked Inactive, by setting the status of the data via a PUT API call, will mark it as such. This will cause it to behave as follows:

  • Any direct calls to the data via GET API calls will succeed
  • Any retrieval of data that references this data point will succeed and show this data
  • Any GetAll API calls to the same entity type (as in, this isn't a child of an object in a different GetAll lookup) that have a status parameter filter of All or Inactive will show this data. But if filtered by Active, then it will not be shown.

The last point may require an example:

  • You save a particular Education Goal reference object as Inactive.
  • If a particular Student has that Education Goal on their Education Goals list, then the responses from a GET to /api/1/person/<SOME_STUDENT_ID> will still return the, now Inactive, Education Goal in the list of all Education Goals for that student. It will be marked as Inactive, but will still be returned.
  • If you call GET /api/1/reference/educationGoal/<ID_OF_INACTIVE_EDUCATION_GOAL> it will return the Inactive Education Goal.
  • If you call GET /api/1/reference/educationGoal/ it will return the active Education Goals
  • If you call GET /api/1/reference/educationGoal/?Status=ALL it will return the Inactive Education Goal, along with the other Active and Inactive Education Goals in the system.
  • If you call GET /api/1/reference/educationGoal/?Status=INACTIVE it will return the Inactive Education Goal, along with the other Inactive Education Goals in the system.
  • But if you call GET /api/1/reference/educationGoal/?Status=ACTIVE, then it will not be returned in the list of Active Education Goals.

The idea behind each status could also be summarized:

  • Active = always returned via the API
  • Inactive = always returned via the API, but the client (consumer of the API) should only show to end-users a read-only view of the object for historical purposes. The client UI should not let the user select an Inactive reference when creating new or modifying existing data. Inactive objects are filtered out if an API service call does not  specify a filter (the default filter is Active) or explicitly requests an Active filter, and only if the direct entity type is Inactive — referenced (children) Inactive data can still be returned. (see the example above)