About the API

The API, as specified here, corresponds to the implementation in Snapper Grape version 2.4.2. 

Please also see documentation for data types returned from the API.

Snapper Grape’s API is RESTful. It is stateless and as simple as possible. The API’s resources are defined by their URIs, and the actions are defined by the http verb used. ”GET” fetches a resource, ”PUT” updates a resource, ”POST” adds a new resource, and ”DELETE” removes the resource. The API is not fully built along these verbs, however. Only the API calls defined in this document are available.

The API always returns a JSON response (see separate document about API types).

Usage and cross-site scripting

The API is designed to be used both in server-to-server communication, and client-to-server, using javascript. Cross-site scripting is supported by the API, but you may need to contact Snapper Net Solutions in order to set this up correctly. 

Consistent return object

Snapper Grape API always returns a JSON object with the following attributes:

valid

Boolean
Indicates whether or not an error occured, or if the operation requested was successful (if request is POST/PUT/DELETE).

message

String
Explanatory string about what has/has not happened. Can be ignored, but can be useful both for debugging purposes, or for conveying to end users what has happened in case of errors.

In addition, the API returns an array of the objects we are asking for. If the call we are requesting is ”/api/personcompetences”, the JSON will have an attribute ”personcompetences”, which holds an array of 0 or more PersonCompetence objects.

All objects described in this document has two representations: simple and full. The simple representation is used when returning lists of objects, or when objects are listed in the context of another object. The full representation is used only when a single object is requested via the objects ID (ie. ”/api/personcompetences/123”). However, the object is still inside an array, for consistency.

So when an API call is defined to return ”Array of person objects”, the actual JSON return will look something like this:

{
    valid: true,
    message: "Returning list of persons",
    persons: [
        {person_id: 123, firstname: "Ola", …},
        {person_id: 124, firstname: "Kari", …}
    ]
}


Quick example

We provide a quick and dirty example of logging in, fetching details for the logged in person, and updating the person’s name. The code is written in javascript, and uses jQuery.

// First, log in
var loginData = {
    user_name: "iamauser",
    password: "passwordsshouldbestrong",
    login: 1
};
$.ajax("/api/login", {data: loginData, dataType: "json", type: "POST", success: afterLogin});

function afterLogin(returnData) {
    // We just assume login was OK. Should check several things here.
    // Fetch person's data
    $.ajax("/api/person", {dataType: "json", type: "GET", success: function(data) {
        console.log(data);
    }});

    // Update person's name
    var updatePersonData = {
        person_data: {
            firstname: "Ola",
            lastname: "Nordmann"
        }
    }
    $.ajax("/api/person", {data: updatePersonData, dataType: "json", type: "PUT", 
      success: function(data) {
        console.log(data);
    }});
}

Errors and error codes

Errors returned from the Snapper Grape API, follow the consistent object described above, but adds a errorcode attribute. The errorcode attribute follows more or less the standard http response codes in the 400-family, with a few additions. The errors and codes defined here are only the ones that are handled explicitly by the API other errors (server error, not found), will give a proper http error response, with http code set to 500/404/etc, according to the webserver’s fancy.


401

Not logged in. The API functions are only available to logged in users.

403

Unauthorized. User is logged in, but is attempting to access a resource or perform an action the user is not authorized to.

404

Not found. The resource requested was not found. This may be because the URL is wrong, or because the ID given in the URL does not match an object in Snapper Grape.

418

Must change password. 418 is outside the http standard. If the password has expired (according to configuration of maximum password age), someone else has changed the user’s password, or a new password has been sent by email, the user is not allowed to do anything until the password is changed. Every request (except one that updates the password) will yield this error response until the password is changed.

419

Missing parameter. Used in the validate function as part of the SSO system.

420

Parameter format error. Something was not correct with the parameters passed. The error message should explain what was wrong.

 

Login and single sign on

Single Sign On

This SSO system assumes that Snapper Grape is master of all user data, and that the client needs to be logged directly in to Snapper Grape. This should only be necessary if you communicate with the API server-to-server, and the end user needs to access Snapper Grape directly at some point, eg. to start an e-course.

See sequence diagram below describing how the SSO system is intended to work.

alt

POST /api/login

Description

Logs a user in to Snapper Grape.

Parameters

user_name

String. User name for user trying to log in.

password

String. Password for user trying to log in.

login

Int. Must be set to 1 in order for the underlying security system to log the user in.

forward_url

String. URL to redirect to after successful login. Redirect is not done in this call, but if we are using SSO, the value of forward_url is relayed.

Return:

Single Login object.

Security:

Anyone

GET /api/validate

Description

Validate if user has a valid session in Snapper Grape. For use in SSO with third-party system, where Snapper Grape is master. Note that this is not a normal JSON request, it actually redirects the client, in order to do make SSO happen.

Parameters

user_name

String. User name of user in question.

hash

String. Short-lived hash, delivered by the login call.

forward_url

String. URL to forward to after successful negotiation.

Return

Redirect or error object

Security

Anyone

GET /api/logout

Description

Log out of Snapper Grape.

Parameters

forward_url

String. URL to forward to after successful logout. Simply relayed to the output.

Return

Single Logout object.

Security

Anyone, but only makes sense when logged in.

POST /api/forgot_password

Description

Resets a user's password

Parameters

identification

String. Identification of user to change password for. Can be user name, email or mobile.

Return:

Simple object containing two attributes: valid (boolean) and message (String)

Security:

Anyone

Person

GET /api/persons/[user_name]

Alias: GET /api/person

Description

Returns person info object for user name. If ”person” alias is used, will always return info for logged in user.

Return

Array of one Person Object

Security

Superuser, person’s manager and self

GET /api/persons/

Description

Returns list of Persons objects. 

Parameters

start

Int. Optional. Index to start at

limit

Int. Optional. Max length of result set

organisation_id

Int. Optional. Limits the result set to members/employees of organisation.

event_id

Int. Optional. Limits the result set to persons signed on to event.

Return

Array of Person objects.

Security

Superuser, organisation’s manager if organisation_id is given

PUT /api/persons/[user_name]

Description

Updates person info for user name

Parameters

person_data

Object. All are optional unless otherwise noted. Not that object must be delivered on the "modern" format: "person_data[firstname]=John&person_data[lastname]=Doe". Only fields present will update person. Can contain the following fields:

  • user_name
  • password
  • firstname
  • lastname
  • jobtitle
  • mobile
  • email
  • birthdate
  • extern_person_id
  • address
  • postcode
  • city
  • phone
  • sex
  • notice
  • employee_code
  • profile_image
  • source
  • code
  • old_password: Required if password or user_name is present, and person is updating self. Not required if manager or superuser is updating. Must match previous password
  • password_match: Required if password or user_name is present, and person is updating self. Not required if manager or superuser is updating.. Must match password.

    
Return

Array of one Person object.

Security

Superuser, person’s manager and self

POST /api/persons New in 2.4.3

Creates new person. Input params are equal to the full view for APIPerson object.

Parameters

organisation_id

Int. Required. Where the new person object should reside.

role_id

Int. Reqired. What role the new person should have in connection to the passed org.

person_data

Json object. Data to update person with. Please note that the 'user_name' must be included in this object. Can contain the following fields:

  • user_name
  • password
  • firstname
  • lastname
  • jobtitle
  • mobile
  • email
  • birthdate
  • extern_person_id
  • address
  • postcode
  • city
  • phone
  • sex
  • notice
  • employee_code
  • profile_image
  • source
  • code

 

Message

GET /api/messages/

Description

Returns list of messages for person.

Parameters

start

Int. Optional. Index to start at

limit

Int. Optional. Max length of result set

user_name

String. Optional. Username identifying the person whose messages we want. If not given, will return messages for logged in person.

Return

Array of Message objects.

Security

Superuser, person’s manager and self

POST /api/messages

Description

Sends a message to user.

Parameters

user_name

String. Username identifying the person to send to.

title

String. Title or subject for message.

text

String. The message.

cc

String. Optional. Addresses to CC to. Separated by comma, semicolon or space

send_medium

String. Optional. ”sms”/”email”/”both”. How to send the message.

reply_to

String. Optional. None/”manager”/. What reply-to address to use. None will yield system’s default.

Return

Array of one Message object.

Security

Superuser, person’s manager and self

GET /api/messages/[message_id]

Description

Returns details for message.

Return

Array of one Message object.

Security

Superuser, person’s manager and self

PersonCompetence

GET /api/personcompetences

Description

Returns list of passed or missing competences for person.

Parameters

start

Int. Optional. Index to start at

limit

Int. Optional. Max length of result set

state

String. Optional. ”passed”/”missing”. Whether to return passed competences or missing competences. Default: ”passed”.

user_name

String. Optional. Username identifying the person whose competences we want. If not given, will return competences for logged in person.

role_ids

List of ints. Optional. IDs of roles to restrict to. Will only yield competences mandatory for these roles.

requirement

String. Optional. None/”mandatory”/”optional”. If set to ”optional”, will return optional instead of mandatory competences. Default: None for state ”passed”, ”mandatory” for state ”missing” or if role_ids is defined

types

List of strings. Optional. Competence types to restrict to.

view

String. Optional. Accepts "simple" and "full". Controls whether to return the full object or a simple representation.

Return

Array of PersonCompetence objects.

Security

Superuser, person’s manager and self

GET /api/personcompetences/[competence_id]

Description

Returns details of competence for person.

Parameters

user_name

String. Optional. If not given, will get competence for logged in user. Only allowed for managers and superusers.

Return

Array of one PersonCompetence object.

Security

Superuser, person’s manager and self

PUT /api/personcompetences/[competence_id]

Note: We use PUT for all updates of person’s competences, as there is no real distinction between creating and updating these. That’s why there is no POST verb.

Description

Updates state of competence for person. What it actually does, depends on the type of the competence:
Common for all types: Registers competence for person, sets dates (verified date and valid until date), stores a comment and file.
Checklist item: Sets the checklist’s state on or off
Signature: Signs digitally, only allowed for self
Formal competence: Sets competence and stores school/university and graduation year
Skill: Stores skill level

Parameters common for all competence types

user_name

String. Optional. If not given, will set competence for logged in user. Only allowed for managers and superusers.

passed

Int, 0-100. Optional, default: 100. Defines passed level for the competence, where 100 is fully passed and 0 is not at all. Mostly for skills, other types should not provide this parameter, usually.

date

String, date on ISO format. Optional, default: now. The point in time from which the competence is valid for the person. 

valid_until

String, date on ISO format. Optional. The point in time where the competence is no longer valid.

comments

Text. Optional. Additional comment to the person’s competence.

file

File. Optional. File to store with the person’s competence. Typically documentation for the competence. NOT IMPLEMENTED.

Parameters applicable for specific competence types

action

String. ”on”/”off”. For checklist items. Determines which state to set the checklist item to. Note: If a person’s manager invokes this, and action is defined, the request is regarded as an attempt to check/uncheck the checklist item as per the item’s setting. However, if action is not defined, the request is regarded as an override to the check/uncheck status of the item, and the competence is set as passed for the person, regardless.

password

String. Person’s password. For signatures when user_name not given. Must be correct in order for the signature to be marked as signed.

show_course_diploma

Boolean. Optional. For courses, module courses, ecourses. If present (and any value), user will be able to download course diploma for the competence.

grade

Floating point number. Optional. For courses, module courses, ecourses. The grade given to the participant.

school

String. Optional. For formal competences. Name of school or university.

graduation_year

String, four digit year. Optional. For formal competences. Year of graduation. 

Return

Array of one PersonCompetence object.

Security

Superuser, person’s manager and/or self, but depending on type and how it is configured. 

DELETE /api/personcompetences/[competence_id]

Description

Removes a competence from a person. Note: If person has completed this competence several times, ALL occurences will be removed.

Parameters

user_name

String. Optional. If not given, will remove competence for logged in user. Only allowed for managers and superusers.

Return

Array of one PersonCompetence object.

Security

Superuser, person’s manager and/or self.

CompetenceLevel

GET /api/competencelevel

Description

Returns object describing competence level for person or organisation.

Parameters

organisation_id

Int. Optional. ID of organisation. If present, will override any user_name given.

user_name

String.  Optional. Username of person. If not given (and organisation_id isn’t given), will return competence level for logged in person.

Return

Array of one CompetenceLevel object.

Security

Superuser, person’s manager, organisation’s manager and self (depending)

Position and Role

GET /api/positions

Description

Returns list of persons positions, with reference to which organisation objects the positions belong to.

Parameters

user_name

String.  Optional. Username of person. If not given, will return positions for logged in person.

Return

Array of Position objects.

Security

Superuser, person’s manager and self

GET /api/roles

Description

Returns list of person’s roles, including positions.

Parameters

user_name

String.  Optional. Username of person. If not given, will return positions for logged in person.

Return

Array of Role objects.

Security

Superuser, person’s manager and self

Competence

GET /api/competences

Description

Returns list of all competences defined and defined as visible for user. Not that this will not return course competences that are modules of a parent course. The modules are nested in the children attribute of the object.

Parameters

start

Int. Optional. Index to start at

limit

Int. Optional. Max length of result set

competence_group_ids

List of ints. Optional. Restricts the result to competences added to these groups.

types

List of strings. Optional. Competence types to restrict to.

view

String. Optional. Defines either 'simple' or 'full' result type.

Return

Array of Competence objects.

Security

Superuser, manager, person

GET /api/competences/[competence_id]

Description

Returns detailed view of competence.

Parameters

view

String. Optional. Defines either 'simple' or 'full' result type.

Return

Array of one Competence object.

Security

Superuser, manager, person

GET /api/competences/[competence_id]/events

Description

Returns a list of events for this competence

/api/events?competence_id=123 will yield the same result as /api/competence/123/events.

Parameters

view

String. Optional. Defines either 'simple' or 'full' result type.

Return

Array of Event objects.

Security

Superuser, manager, person

CompetenceGroup

GET /api/competencegroups

Description

Returns list of competence groups.

Parameters

all

Int. Optional. 0/1. If 1, return all competence groups, regardless of hierarchy. If 0, returns only root competence groups. Default 0.

Return

Array of CompetenceGroup objects.

Security

Superuser, manager, person

GET /api/competencegroups/[competence_group_id]

Description

Returns detailed view of  competence group, and list of sub competence groups.

Return

Array of one CompetenceGroup object.

Security

Superuser, manager, person

Event

GET /api/events

Description

Returns list of course events. Note that this will not return events that are modules of a parent course. These are nested in the children attribute of the object.

Parameters

view

String. Optional. Specifies either "full" or "simple" result type.

competence_id

Int. Optional. To list only events belonging to a specific competence.

organisation_ids

List of ints. Optional. Only return events that have participants belonging to Organisations.

recursive

Int. Optional. 1 or 0. Whether or not parameter organisation_ids should result in a recursive, tree search for participants or not. If set, will return events with participants belonging to branches of organisation tree defined by organisation_ids. Default: 0

 

start

Int. Optional. Index to start at.

limit

Int. Optional. Max length of result set.

mode

String. Optional. ”future”/”finished”/”all”.  Controls if we are to get future or finished events, or both. Default: ”future”

startdate

String, date on ISO format. Optional. Return only events starting on or after this time. Overrides ”mode” parameter.

enddate

String, date on ISO format. Optional. Return only events starting before this time. Overrides ”mode” parameter.

sort_direction

String. "asc"/"desc". Whether the result should be sorted ascendingly or descendingly. Default: "asc". 

Return

Array of Event objects.

Security

Superuser, manager, person

GET /api/events/[event_id]

Description

Returns detailed view of course event.

Parameters

view

String. Optional. Specifies if you want either 'full' or 'simple' result type.

Return

Array of one Event object.

Security

Superuser, manager, person

GET /api/events/[event_id]/participants

Description

Returns a list of participants (Person) for the course event.

/api/participants/123 will yield the same result as /api/events/123/participants.

Parameters

view

String. Optional. Specifies if you want either 'full' or 'simple' result type.

Return

Array of Person objects.

Security

Superuser, manager, person

PersonEvent

GET /api/personevents

Description

Returns list of events user is signed on to.

Parameters

user_name

String. Optional. User name for user. Will return for logged in user if not present.

start

Int. Optional. Index to start at.

limit

Int. Optional. Max length of result set.

mode

String. Optional. ”future”/”finished”/”all”.  Controls if we are to get future or finished events, or both. Default: ”future”

waitlist

Int. Optional. 0/1. Return events for which person is on waitlist or not. Default 0.

organisation_id

Int. Optional. Return personevents for persons belonging to organiasation unit. Will override user_name parameter.

Return

Array of PersonEvent objects.

Security

Superuser, manager, self

GET /api/personevents/[event_id]

Description

Get detailed view of event for person. Will return empty list if person is not signed on to event.

Return

Array of one PersonEvent object.

Security

Superuser, manager, self

POST /api/personevents/[event_id]

Description

Signs person on to course event.

Parameters

user_name

String. Optional. Username for user to be signed on.

order_id

Int. Optional. ID of order to add this sign on to. Only valid if order system is enabled.

order_reference

String. Optional. Order reference for new order that is created. Only valid if order system is enabled. Ignored if parameter order_id is given.

Return

Array of one PersonEvent object.

Security

Superuser, manager, self

PUT /api/personevents/[event_id]

Description

Signs person off course event. Or otherwise alters the sign on data (not specified or implemented yet).

Parameters

user_name

String. Username for user.

action

String. ”off”/”update”. Action to take. ”off” signs person off event.

Return

Array of one PersonEvent object.

Security

Superuser, manager, self

Location

GET /api/locations

Description

Get all locations registered in system

Parameters

view

String. Optional. "full" or "simple" view of object.

Return

Array of Location objects

Security

All logged in users

GET /api/locations/:location_id

Description

Get location object.

Parameters

location_id

Int. Unique ID for location object.

view

String. Optional. "full" or "simple" view of object.

Return

Single Location object

Security

All logged in users

Participant

GET /api/participants/:event_id

Description

Returns list of Participant objects for event.

Parameters

event_id

Int. ID for the event to get participants for.

waitlist

Int. Optional. 1/0. If 1, will return only participants on wait list. If 0, will return only participants not on waitlist. If unset, will return both.

passed

Int. Optional. 1/0. If 1, will return only participants who have passed the course. If 0 will return only participants who did not pass the course. If unset, will return both.

met

Int. Optional. 1/0. If 1, will return only participants who met for the course. If 0 will return only participants who did not meet for the course. If unset, will return both.

organisation_id

Int. Optional. ID of organisation, will restrict participants to only those who are employed here.

recursive

Int. Optional. 1/0. If set, organisation_id will be user recursively, looking down the organisation tree branch.

view

String. Optional. "full"/"simple". What view to use.

start

Int. Optional. Index to start at.

limit

Int. Optional. Max length of result set.

Return

Array of Participant objects.

Security

Superuser, organisation’s manager if organisation_id is given

GET /api/participants/:event_id/:user_name

Description

Returns single Participant for event.

Parameters

event_id

Int. ID for the event to get participant for.

user_name

String. Optional. User name for user.

view

String. Optional. "full"/"simple". What view to use.

Return

Single Participant objects.

Security

Superuser, person's manager, self

Organisation

GET /api/organisations

Description

Returns list of organisation objects.

Parameters

start

Int. Optional. Index to start at

limit

Int. Optional. Max length of result set

parent_id

Int. Optional. Restricts result set to organisation objects belong to this parent. parent_id=0 yields only root organisation objects.

user_name

String. Optional. Person’s username. If given, will return list of organisations person belongs to.

Return

Array of Organisation objects.

Security

Superuser, manager, will yield different results based on manager’s permissions

GET /api/organisations/[organisation_id]

Description

Returns detailed view of organisation object. :id is organisation ID.

Return

Array of one Organisation object.

Security

Superuser, manager, only available to manager if manager for this particular object

GET /api/organisations/[organisation_id]/persons

Description

Returns list of people in the organisation object.

/api/persons?organisation_id=123 will yield the same result as /api/organisations/123/persons.

Parameters

view

Optional. String. Either None or 'full' or 'simple'

Return

Array of Person objects.

Security

Superuser, manager, only available to manager if manager for this particular object

POST /api/organisations

Returns list of one organisation object that was created.

Test example:
            
curl http://pet/api/login --data "user_name=peen&login=1&password=fdsafdsa"

Use "session_id" from the result an set as tg-visit cookie:

curl --cookie "tg-visit=03dd783b1051326e110487a4125c52fceafdefee" --data "organisation_data[name]=TestUnitI&organisation_data[parent_id]=10&organisation_data[email]=jost@snapper.no&organisation_data[address]=Brattvollveien+261" http://pet/api/organisations

Creates a new organisation object.

organisation_data

Please note thet the reference to a parent organisation should be included in this parameter. If not passing or passing a parent_id=0 will make the new organisation object a root organisation.

Return

list of one APIOrganisastion object if successful.

CompetenceType

GET /api/competencetypes

Description

List of competence types defined in the system

Return

Array of CompetenceType objects.

Security

Superuser, manager, person

LMSStartURL

GET /api/lmsstarturls

Description

Returns list of start URLs for the LMS configured in the system.

Parameters

competence_ids

List of ints. Optional. If not given, all URLs for all ecourse competences are returned.

Return

Array of LMSStartURL objects.

Security

Superuser, manager, person