API - Technical specification
Background
​
Kippy is accessible via simple web APIs to push and pull information from and to the your kippy instance. This page summarizes the mechanism to invoke those APIs.
​
​
Introduction
​
Below is a sample url to invoke one of the APIs
​
​
The parts of the url are explained below:
​
https://kippy-tsc.appspot.com/ - the hostname of the kippy API server
​
/api/v4/query/ - the path to the API to call, in this example the v4 query API
​
username=o@51aug.com - the id of the user who is making this call, in this example an admin user
​
organisation=51aug.com - the kippy instance this call is made against, in this example 51aug.com
​
table=appraisal - the kippy table this v4 query API will query, in this example, the appraisal table
​
filter.year=2023 - the attribute of the appraisal table the v4 query API should filter on, in this example, filter appraisals where year is 2023
​
filter.appraiseeUserId=m@51aug.com - another attribute of the appraisal table the v4 query API should filter on, in this example, filter appraisals where the appraisee is the user m@51aug.com.
​
Note on filters:
1) all filters are exact equality match
2) all filters are composite AND filters
3) filters take the form "filter." and the name of the attribute to filter
4) filters can only be performed on attributes that have been indexed on the backend
​
Authentication: The password for the username above is 25d6d58e76c14765895d9a968a66012b. To call the API with an authentication token see the example here.
​
v4 API
​
Query API
​
The following tables are currently support in the v4 Query API. Contact support for access to other tables.
- user
- appraisal
- team
- annualScore
- teamScore
- audit
- note
​
Note on response:
1) All results are limited to 1000 items.
2) See above for filtering
3) Successful calls return JSON.
4) Unsuccessful calls return empty response
5) The JSON attributes in the response should be self-explanatory - contact support for clarifications
6) The responses are physical representations of the underlyign data model
​
v3 API
​
​
This is an example of a call to get all KPIs for given board
​
https://kippy-tsc.appspot.com/api/v3/kpis/?username=owner@thesolutioncrowd.com&organisation=thesolutioncrowd.com&dashboard=CEO&filterUser=m@thesolutioncrowd.com&filterYear=2023
​
dashboard=CEO - The dashboard is the name of Kippy team to return KPIs for, in this example for the CEO team
​
filterUser=m@thesolutioncrowd.com - this is to ensure only dashboards and KPIs 'of interest' to filtered user are return, in this example, KPIs for the team of the CEO are only returned if m@thesolutioncrowd.com is part of the CEO team (or is an owner for KPI on the CEO team)
​
filterYear=2023 - do not show KPIs that are inactive for the given year, in this example, 2023.
​
Notes on reponse:
1) This is a consumer driven contract so some attributes are atypical e.g. teams are called departments, perspectives are called dimension, etc.
2) The /api/v3/projecs/ API can be used to retrieve information on projects
3) The /api/v3/kpis/scores/ and /api/v3/projects/scores/ APIs add score information to the response
4) Contact kippy support for info on other v3 APIs to push and pull data
NB A valid JWT token is needed for authentication.
​
​