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
- competency
- feedback
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.