top of page

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

https://kippy-tsc.appspot.com/api/v4/query/?username=o@51aug.com&organisation=51aug.com&table=appraisal&password=25d6d58e76c14765895d9a968a66012b&filter.year=2023&filter.appraiseeUserId=m@51aug.com

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

password=25d6d58e76c14765895d9a968a66012b - the plain text password of the user making this call, contact support for other auth mechanisms

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

v4 API

Query API

The following tables are currently support in the v4 Query API. Contact support for access to other tables.

 

- appraisal

- team

- annualScore 

- teamScore

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&password=123123129dfsdkjfssdas

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 

bottom of page