Difference between revisions of "Developers/API"

From PartKeepr Wiki
Jump to: navigation, search
(add example to retrieve the storage locations id)
(add better way to get the content of a storage location)
Line 49: Line 49:
 
== Filtering examples ==
 
== Filtering examples ==
  
Filtering by the storage location:
+
Filtering by the storage location ID:
  
 
<pre>curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"storageLocation","operator":"=","value":"/api/storage_locations/3"}</pre>
 
<pre>curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"storageLocation","operator":"=","value":"/api/storage_locations/3"}</pre>
Since you cannot perform the lookup by the storage locations name right now, you can the the id (3 in the example above), by searching for the exact name of your location by running a request like:
+
You can get the ID by searching for the name of the storage location like this:
 
<pre>curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/storage_locations?filter={"property":"name","operator":"=","value":"FELI-HOME-A003"}</pre>
 
<pre>curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/storage_locations?filter={"property":"name","operator":"=","value":"FELI-HOME-A003"}</pre>
 +
Or both in one query:
 +
<pre>curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"storageLocation.name","operator":"=","value":"FELI-HOME-A003"}</pre>
  
 
== Filtering by the status ==
 
== Filtering by the status ==
  
 
<pre>curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"status","operator":"LIKE","value":"new"}</pre>
 
<pre>curl --globoff --basic --user admin:admin http://demo.partkeepr.org/api/parts?filter={"property":"status","operator":"LIKE","value":"new"}</pre>

Revision as of 15:21, 22 May 2016

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"}