Developers/API

Introduction

PartKeepr uses JSON-LD/Hydra-CG as API standards.

Authentication can be done by HTTP Basic and/or WSSE. Once authenticated, a session cookie is set, but you can also re-send the HTTP Basic and/or WSSE auth on every request.

API Documentation

http://demo.partkeepr.org/api/apidoc

To view the API Doc, you need to go to http://demo.partkeepr.org to receive a session cookie.

Unfortunately a user-friendly API doc is not available yet due to a problem with a 3rd party library. However, the hydra documentation should give some clues which API calls are available.

Example HTTP Request

GET https://demo.partkeepr.org/api/parts

HTTP Headers:
Authorization:Basic YWRtaW46YWRtaW4=
Host:demo.partkeepr.org

CURL Examples

Basic Example

Retrieves all parts with pagination defaults:

curl --basic --user admin:admin http://demo.partkeepr.org/api/parts

Please keep in mind to escape the following characters in your shell: "?[]{}=& (and space). Example:

/api/storage_locations?filter={"property":"name","operator":"=","value":"FELI-HOME-A003"}

becomes:

/api/storage_locations\?filter\=\{\"property\":\"name\",\"operator\":\"\=\",\"value\":\"FELI-HOME-A003\"\}

Also using --globoff as curl parameter helps too, otherwise you would have to escape certain characters a second time because curl tries to expand the URL too. We'll stick to the unescaped form for better readability right now.

Pagination example

curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?page=5&start=0&itemsPerPage=50

If you want all parts, you need to request a quite big amount of itemsPerPage like:

curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?page=0&start=0&itemsPerPage=9999999999

Filtering examples

Filtering by the storage location ID:

curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"storageLocation","operator":"=","value":"/api/storage_locations/3"}

You can get the ID by searching for the name of the storage location like this:

curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/storage_locations?filter={"property":"name","operator":"=","value":"FELI-HOME-A003"}

Or both in one query:

curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"storageLocation.name","operator":"=","value":"FELI-HOME-A003"}

Filtering by the status

curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"status","operator":"LIKE","value":"new"}

Easy way to figure out the needed request / workaround for the missing API documentation

Use chrome, login and prepare to perform the action you would like to do.

Press F12, choose the network tab, select XHR.

Perform the action and search for the correct post request on the right site in the network tab.

Right-click -> "Copy as cURL".

Replace what you need (like supplementing login credentials instead of a session cookie and so on) and keep on scripting :).