Skip to content

Commit 421498f

Browse files
kevinpapstkevinpapst
committed
added api examples
1 parent a7def27 commit 421498f

File tree

6 files changed

+305
-160
lines changed

6 files changed

+305
-160
lines changed

‎_data/menu-documentation.yml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,13 @@ developer:
8989
icon: bx bx-code
9090
name: JSON API
9191
description: Use the JSON API to fetch and create data in Kimai
92-
pages: [rest-api, rest-api-examples, api-pagination]
92+
pages: [rest-api, api-pagination]
93+
-
94+
id: examples
95+
icon: bx bx-code
96+
name: API Examples
97+
description: Real world examples of using the Kimai API
98+
pages: [rest-api-examples, api-example-javascript, api-example-sync, api-example-user]
9399
-
94100
id: developer
95101
icon: bx bx-git-branch

‎collections/_documentation/developer/api-example-javascript.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: Calling the API with Javascript
3+
navigation: jQuery Demo
4+
description: A jQuery example accessing the Kimai API
5+
related:
6+
- rest-api
7+
- rest-api-examples
8+
---
9+
10+
If you develop your own [plugin]({% link _documentation/developer/plugins.md %}) and need to use the API for logged-in
11+
user,
12+
then you don't have to care about authentication, Kimai will handle it for you.
13+
14+
Copy & paste this code into a new `api.html` file and open it in your browser.
15+
You can execute some sample requests and see the JSON result.
16+
17+
```html
18+
<!doctype html>
19+
<html lang="en">
20+
<head>
21+
<meta charset="utf-8">
22+
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
23+
<title>Kimai - API demo</title>
24+
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css">
25+
<link rel="stylesheet" href="https://getbootstrap.com/docs/4.3/examples/floating-labels/floating-labels.css">
26+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.15.0/themes/prism.min.css">
27+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.15.0/plugins/line-numbers/prism-line-numbers.min.css">
28+
<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
29+
<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.7/umd/popper.min.js"></script>
30+
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js"></script>
31+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.15.0/prism.min.js"></script>
32+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.15.0/components/prism-json.min.js"></script>
33+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.15.0/plugins/line-numbers/prism-line-numbers.min.js"></script>
34+
<style>
35+
body {
36+
display: block;
37+
}
38+
39+
.codePreview {
40+
margin-top: 30px;
41+
}
42+
</style>
43+
<script>
44+
function callKimaiApi(method, successHandler, errorHandler) {
45+
var domain = $('#inputDomain').val();
46+
var token = $('#inputToken').val();
47+
$.ajax({
48+
url: domain + '/api/' + method,
49+
type: 'GET',
50+
beforeSend: function (request) {
51+
request.setRequestHeader('Authorization', 'Bearer ' + token);
52+
},
53+
headers: {
54+
'Authorization': 'Bearer ' + token,
55+
},
56+
success: successHandler,
57+
error: errorHandler
58+
});
59+
}
60+
61+
$(function () {
62+
$('#loginForm').on('submit', function (event) {
63+
event.preventDefault();
64+
event.stopPropagation();
65+
$('#loginButton').text('Loading...');
66+
callKimaiApi('version', function (result) {
67+
$('#loginButton').text('Success');
68+
$('.secret').attr('style', 'display:block');
69+
return false;
70+
}, function (xhr, err) {
71+
$('#loginButton').text('Try again!');
72+
$('.secret').attr('style', 'display:none');
73+
console.log(xhr);
74+
alert('Error occured, see console for details');
75+
}
76+
);
77+
return false;
78+
});
79+
80+
$('button[data-api]').on('click', function (event) {
81+
event.preventDefault();
82+
event.stopPropagation();
83+
84+
var apiMethod = $(this).attr('data-api');
85+
var breakAttr = $(this).attr('data-attribute-break');
86+
$('#loginButton').text('Loading...');
87+
88+
callKimaiApi(
89+
apiMethod,
90+
function (result) {
91+
$('#loginButton').text('Success!');
92+
var jsonBeauty = JSON.stringify(result).trim();
93+
if (breakAttr === "true") {
94+
jsonBeauty = jsonBeauty.split('","').join('",' + "\n" + '"');
95+
}
96+
jsonBeauty = jsonBeauty.split('},{').join('},' + "\n" + '{');
97+
$('#apiResult').text(jsonBeauty);
98+
$('.codePreview').attr('style', 'display:block');
99+
Prism.highlightElement(document.getElementById('apiResult'));
100+
return false;
101+
}, function (xhr, err) {
102+
$('#loginButton').text('Sorry, that failed :-(');
103+
console.log(xhr);
104+
alert('Error occured, see console for details');
105+
}
106+
);
107+
return false;
108+
});
109+
});
110+
</script>
111+
</head>
112+
<body>
113+
<div class="container">
114+
<form id="loginForm" class="form-signin">
115+
<div class="text-center mb-4">
116+
<h1 class="h3 mb-3 font-weight-normal">Kimai &ndash; API Demo</h1>
117+
<p>Please provide your API URL and token below</p>
118+
</div>
119+
<div class="form-label-group">
120+
<input type="url" id="inputDomain" class="form-control" placeholder="https://www.example.com/" required
121+
autofocus value="https://demo.kimai.org">
122+
<label for="inputDomain">Kimai base URL (domain + port)</label>
123+
</div>
124+
<div class="form-label-group">
125+
<input type="text" id="inputToken" class="form-control" placeholder="API Token" required
126+
value="api_kitten_super">
127+
<label for="inputToken">API Token</label>
128+
</div>
129+
<button class="btn btn-lg btn-primary btn-block" id="loginButton" type="submit">Sign in</button>
130+
</form>
131+
<div class="row secret" style="display:none">
132+
<div class="col-sm text-center">
133+
<button type="button" class="btn btn-primary" data-api="ping" data-attribute-break="true">Ping</button>
134+
<button type="button" class="btn btn-secondary" data-api="version" data-attribute-break="true">Version</button>
135+
<button type="button" class="btn btn-secondary" data-api="plugins" data-attribute-break="true">Plugins</button>
136+
<button type="button" class="btn btn-primary" data-api="timesheets" data-attribute-break="false">Timesheet</button>
137+
<button type="button" class="btn btn-primary" data-api="activities" data-attribute-break="false">Activities</button>
138+
<button type="button" class="btn btn-primary" data-api="projects" data-attribute-break="false">Projects</button>
139+
<button type="button" class="btn btn-primary" data-api="customers" data-attribute-break="false">Customers</button>
140+
</div>
141+
</div>
142+
<div class="row codePreview" style="display:none">
143+
<pre class="language-json line-numbers" style="white-space: pre-line">
144+
<code id="apiResult"></code>
145+
</pre>
146+
</div>
147+
</div>
148+
</body>
149+
</html>
150+
```
151+

‎collections/_documentation/developer/api-example-sync.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: Sync your Kimai data via API to a local database
3+
navigation: Sync to a local DB
4+
description: Full example application, syncing all data to a local source for integrated reporting
5+
related:
6+
- rest-api
7+
- rest-api-examples
8+
---
9+
10+
Tired of exporting Excel to import it into Power BI?
11+
12+
Use this script and let it run every night to sync the delta from last night: [https://github.com/kimai/api-sync](https://github.com/kimai/api-sync).
13+
14+
Then point your BI solution to the local database.
15+
16+
## Requirements
17+
18+
- Requires PHP >= 8.1.3
19+
- MySQL 8
20+
- GIT
21+
- Composer (siehe https://getcomposer.org/download/)
22+
23+
## Installation
24+
25+
- Clone the repo: `git clone [email protected]:kimai/api-sync.git kimai-api-sync`
26+
- Create the database and then the necessary tables, structure can be found in `database.sql`
27+
- Execute `php composer.phar install --optimize-autoloader -n`
28+
- Edit `configuration.php` and adjust settings to your needs
29+
30+
## Usage
31+
32+
The sync script can be run with `php sync.php` and it has two optional parameters:
33+
34+
- `--modified="2024-01-01 12:00:00"` - only sync timesheets, which were changed after a certain date-time, format: `YYYY-MM-DD HH:mm:SS`
35+
- `--timesheets` - only sync timesheets
36+
37+
If `--modified` is skipped, only the latest 24 hours will be synced
38+
39+
## Initial sync
40+
41+
For the initial sync you should choose a date far in the past, so all non-synced timesheets will be fetched:
42+
43+
```
44+
php sync.php --modified="2020-12-31 00:00:00"
45+
```
46+
47+
## Cronjob
48+
49+
Now you can easily fetch latest changes via cronjob.
50+
51+
If you installed the project into `/opt/kimai-api-sync/` and want to sync once a night you might want to use something like:
52+
53+
```
54+
17 3 * * * /usr/bin/php /opt/kimai-api-sync/sync.php --modified="2020-12-31 00:00:00" --timesheets >> /var/log/kimai-api-sync.log 2>&1
55+
```

‎collections/_documentation/developer/api-example-user.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
title: Setting user preferences for automated onboarding
3+
navigation: Onboarding users
4+
description: Creating user and configuring their preferences with the API allows for automated onboarding workflows
5+
related:
6+
- rest-api
7+
- rest-api-examples
8+
---
9+
10+
For larger companies, it is often easier to pre-sync user accounts to Kimai, instead of creating them with the UI.
11+
12+
The API has the following endpoints:
13+
14+
- `GET /api/users/{id}` - for reading one user
15+
- `POST /api/users` - for creating users
16+
- `PATCH /api/users/{id}/preferences` - for updating settings
17+
18+
Please read the API docs to understand the exact requests.
19+
20+
21+
## Configure contracts with user-preferences
22+
23+
You can configure working contracts [using the API]({% link _documentation/developer/rest-api.md %}).
24+
All settings are kept in user-preferences, so you can set them with the `PATCH /api/users/{id}/preferences` endpoint.
25+
26+
**Contract Types**
27+
28+
Please note that some contract types are only available with the [Working contract plugin]({% link _store/keleo-controlling.md %}) or the `Pro` cloud plan.
29+
30+
**Type "month" - Total monthly hours**
31+
32+
```json
33+
[
34+
{"name": "work_contract_type", "value": "month"},
35+
{"name": "hours_per_month", "value": "432000"},
36+
{"name": "work_days_month", "value": "1,2,3,4,5"}
37+
]
38+
```
39+
40+
**Type "week" - Total weekly hours**
41+
42+
```json
43+
[
44+
{"name": "work_contract_type", "value": "week"},
45+
{"name": "hours_per_week", "value": "144000"},
46+
{"name": "work_days_week", "value": "1,2,3,4,5"}
47+
]
48+
```
49+
50+
**Type `day` - Individual daily hours**
51+
52+
```json
53+
[
54+
{"name": "work_contract_type", "value": "day"},
55+
{"name": "work_monday", "value": "28800"},
56+
{"name": "work_tuesday", "value": "28800"},
57+
{"name": "work_wednesday", "value": "28800"},
58+
{"name": "work_thursday", "value": "28800"},
59+
{"name": "work_friday", "value": "14400"}
60+
]
61+
```
62+
63+
**Available Preferences**
64+
65+
| Preference | Example | Description |
66+
|--------------------------------|---------------------------|--------------------------------------------------------------------|
67+
| `work_contract_type` | `week` or `day`or `month` | Contract type |
68+
| `hours_per_week` | `144000` | Weekly hours in seconds (144000 = 40h) |
69+
| `hours_per_month` | `144000` | Monthly hours in seconds (432000 = 120h) |
70+
| `work_monday` .. `work_sunday` | `28800` | Daily hours in seconds (28800 = 8h) |
71+
| `work_days_month` | `1,2,3,4,5` | Work days for contract type `month` (1=Monday, 5=Friday, 7=Sunday) |
72+
| `work_days_week` | `1,2,3,4,5` | Work days for contract type `week` (1=Monday, 5=Friday, 7=Sunday) |
73+
| `holidays` | `30` | Vacation days per year |
74+
| `public_holiday_group` | `1` | Holiday group ID |
75+
| `work_start_day` | `2025-01-01` | Contract start |
76+
| `work_last_day` | `2027-12-31` | Contract end (optional) |
77+
{: .table }

0 commit comments

Comments
 (0)