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);
}});
}
