OSDI Client
Library for interacting with any OSDI compliant server (http://opensupporter.github.io/osdi-docs/).
Will parse the app entry point and returned metadata on subsequent api calls and create convenience methods for you.
Note: I haven't finished populating the Resource classes with the correct property fields.
Usage
Works in the browser and in node. Browersify / webpack friendly.
npm install --save osdi-client
const osdi = require('osdi-client')
osdiClient.client('https://sample-system.com/api/aep')
.then(client => {
// ready to use client
})
.catch(err => {
})
Relies on superagent
(https://github.com/visionmedia/superagent) for most of
the heavy lifting, so get familiar with their API first.
osdi.client
The initialization method returns a promise, which is resolved with an client
object or reject with whatever error.
osdi.client
accepts an the API's app entry point...
osdi
or you can give it the JSON data that lives at the app entry point directly, and save a network request.
osdi
client.get
The client
object generated by osdi.client
will have all of the exposed
resources created as get methods.
So, for example, if the AEP (app entry point) has osdi:people
and osdi:events
,
client
will have client.getPeople()
and client.getEvents()
.
These methods will return a superagent
request, which can be called with .end
as in
client
or with .then
and .catch
as in
client
And since superagent
supporters promises, you can do
async myFunc () {
const people = await client.getPeople()
// do something with people
}
Since the get<Resource>
methods return a superagent
request, you can manually
add headers with .set
, modify query parameters, etc.
client
Helper methods for queries and authentication are planned but not implemented yet.
Resource Objects
For whatever resources the app entry point exposes, a resource class will be
available from client.resources
. These classes have .save
, .delete
, and
getter / setters for any attribute in the OSDI docs. .save
and .delete
also
expose superagent
requests.
*** Note *** --- I have chosen to make all properties camel case, so family_name
becomes familyName
. This is all done behind the scenes. I did it because most
Javascript uses camelCase, but if you think it's a bad decision (leads to unnecessary confusion)
let me know.
So for example, to create a new event...
const party = name: 'Pizza Party' title: 'Happy Birthday' description: 'Celebrating Pizza\'s Birthday' console // 'Pizza Party'partyname'Pizza\'s Birthday Party'console // 'Pizza's Birthday Party' party
client.parse
Parsing Responses with Calling client.parse
on the response will serialize its metadata into function
calls and wrap its embedded response data inside Resource classes. For example:
client
To make everyone in the database named Greg, simply
{ Promiseall responsepeople }
Manually Editing a Resource
All of a resources data live at person.data
or event.data
or whatever. However,
if you manually modify .data
and then call .save
, the Resource will not know
the given field has been modified, and so it will not include it in the body of
the request generated by resource.save()
. To make sure it gets included, use
resource.markModified('field')
.
// BAD!!!!persondatagivenName = 'Thomas'person // OK!!!persondatagivenName = 'Thomas'personperson // PREFERRED!!!personperson
Tests
Written with Mocha, Chai, and node-nock. npm test
does the trick.