REST API documentation

[1am]

Hi,

Is there some reference of the REST API provided by PartKeepr? I'd like to know more on the possibilities of integrating with different tools before I start putting all inventory into the system.

Best regards, PB

[Drachenkaetzchen]

Yes, the HydraCG API Docs are in place:

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.

[1am]

Thank you for pointing me towards the apidoc. How should the authentication against API be performed? Is there a example I could look at for for performing and authenticate + search part routine?

[Drachenkaetzchen]

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.

Example HTTP Request:

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

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

CURL Example:

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

Pagination example

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

Filtering examples

Filtering by the storage location:

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

Filtering by the status:

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

[Drachenkaetzchen]

The API samples have been added to https://wiki.partkeepr.org/wiki/Developers/API

[watersAbove]

These examples cover the nice and easy basic authentication case, but fail to cover WSSE, which requires using an api method that is not in the generated hydra api documented (due to it being a controller, mapped to an api path).

for WSSE you must post to /api/getSalt with a json post parameter object like this {"username":""}

The returned salt is then utilised in the calculation of the authentication header for your first 'get' /api/apidoc, where if successful, returns a session token for easier authentication from there on forward, until the token is expired.

[watersAbove]

I've got my Partkeepr API client now working, and interacting with the REST webservices, which is the majority of the battle behind me.

Written in Java using OpenFeign to access and describe the Partkeepr API. WSSE Digest Authentication interceptor in the Partkeepr style Uses Annotated POJOS to access data, serialised via jackson (other options available) There's a lot more work to do, but I envision this is a component that is used to integrate into a more robust service gate, which handles more complex tasks, utilising this component piece in more complex service routes.

Some issues I had:

Problems with hard coded paths. If you use a context path, like I do prepare to have a bad time. There were redirect issues with the configuration, so keep that in mind. JSONLD - this was not so much a problem but a learning curve associated with JSON-LD/Hydra style linked data apis. No way to discover actual endpoint paths: it took a long time to get at the API endpoints(they are different than the documented element paths. They are similar to the Object type, but usually different.. example "storageLocation" API endpoint maps to "storage_locations". I'm not sure the best way to share this, but I can expose the OpenFeign Partkeepr API probably as a github project. Sorry it's not PHP, but I don't like PHP it turns out :)

[rossvonfange]

@brads4 will you be posting any of your code (even snippits to pastebin) any time soon? I'm trying to use the API with python in hopes linking parts to my kicad library and could probably learn a lot from your java code.

[watersAbove]

Yes, i can give it out. It doesn't have full coverage, but it's got enough that adding consumer methods is fairly trivial. It' also doesn't consider JSON LD schema at this point. I'll post it later today, and it'll be free to use in any way.

[lookme2]

Any update on this? I also am trying to interface with python. I am not having much luck at this point.

[Drachenkaetzchen]

@lookme2 no, lack of time. Try to read the JSON-LD requests sent by the frontend

[lookme2]

I've done that. I can get info out of PartKeepr but cant find a way to but it back in.

[Drachenkaetzchen]

@lookme2 well you basically POST or PUT an object. The frontend does the same thing. Without the info what you want to achieve and what you have tried its hard to tell what's going wrong. You can create a new issue so we can try to work on this if you want.

[christianlupus]

@baradhili What do you think of this issue?

[baradhili]

@christianlupus it does need to be done at some stage in order to drive integration...
I'm not a Symfony dev.. but this looks here like a solution

I'd suggest this is a Must Have priority, but also Good-first-issue

[christianlupus]

OK, I'll go with it.