hal-rest-client
hal-rest-client library to help you work with Hypertext Application Language (HAL) on Typescript. It's work fine with browser or nodejs app.
It can map rest service return to Typescript object for simply access link or property.
Install
Using npm :
npm install hal-rest-client
From 0.2
Warning : uri
property of HalResource are now URI
type. Si if you use this property you must now use
halResource.uri.fetchedURI // get the uri used to fetch resourcehalResource.uri.uri // get the uri provided from serverhalResource.uri.fill // fill the templated uri with given parameters
How to use
The library provide two access method :
- use generic object
HalResource
to map service return - map service return on typescript object
model
HalResource
Generic Usage : using Read object
To have access to your service, you need to create an hal-rest-client instance .
;;// or;
To get a resource, you can use fetchResource method.
or;
fetchResource return a promise. you can use
then
andcatch
to get result. Otherwise you can useawait
see this article
you can get resource property, embedded property or link using prop
method.
;;
for a link, on link
service return
;// or;
link attribute type is
HalResource
Follow a link
Links are made to be followed. So you can simply fetch a link using fetch
method.
;await link.fetch;;
Note that link()
returns an empty HalResource
with its uri
set. You need to call fetch()
to populate the HalResource.
The library also supports arrays of links using Array syntax:
;await link.fetch;;
Follow a templated link
If you link is templated, you can set parameter to fetch to compute fetch URL.
// link "link_name" is a templated link like this // /bookings{?projection};; // fetch /bookings; // fetch /bookings?projection=name
// link "link_infos" is like this // /infos{/path*};; // fetch /infos;
Links as props
Note that named links are synonymous with props:
;;link === prop // true
This means you can navigate a HAL hierarchy (referencing and fetching) using props alone:
// using .prop();; // using .linksbar.props === resource.links.foo.links.bar.props // true
Update a resource
Resource can be updated, an save with a PATCH query.
resource.prop"name", "new value";await resource.update
update return a promise. use
await
to wait end of update.
To set a link, you can use prop
or link
function. the new value for a link must be an HalResource
populated or not.
// init an HalResource called newResourceresource.prop"link_name", newResource;await resource.update;
on the request send to server, only the uri is sent not all the object.
Create a resource
To create a resource, you must use method create
on your client.
await client.create"/resources", ;
If your server return the new created object as body, you can do this :
;
Resource is an HalResource if server return a resource or just json if a simple json is returned
With model usage
hal-rest-client can use model class to fetch HAL rest result. Model class is a definition of service return.
Create a model class
for this exemple, we create a Resource model.
;;
your model must extends HalResource
each property must be annoted with
@HalProperty
. _links, _embedded, an simple props must to be map with@HalProperty
Read an object
To read an object, you need to create a client, and call fetch
method.
;;// or;
call fetch method
;;
fetch return a promise. you can use
then
andcatch
to get result. Otherwise you can useawait
see this article
Read props is simply call object attributes.
;;
Follow a link
links are made to be followed. So you can simply fetch a link using fetch
method.
await resource.owner.fetch;;
mapped links return an empty
HalResource
, justuri
is setted. Callfetch
populate the HalResource.if ower is not a link but an embedded resource, you don't need to call
fetch
. Object is populate with embedded resource
fetch return the fetched object, so you can do that :
;;
you can fetch a templated link like this
// link "booking" is a templated link like this// /bookings{?projection}; // fetch /bookings; // fetch /bookings?projection=name// link "infos" is like this// /infos{/path*}; // fetch /infos;
update a resource
Resource can be updated, an save with a PATCH query.
resource.name = "new value";await resource.update
update return a promise. use
await
to wait end of update.
You can set a link, the new value for a link must be an HalResource
or an other model, populated or not.
// init an HalResource called newPersonresource.owner = newPersonawait resource.update;
on the request send to server, only the uri is sent not all the object.
create a resource
To create a resource, you have two choices :
- use
create
method on client - create a resource object and call
create
method on this object
Use the client
To create a resource, you must use method create
on your client.
await client.create"/resources", ;
If your server return the new created object as body, you can do this :
;
Resource is an Resource object if server return a resource or just json if a simple json is returned
Create a new Object
To create a resource object, you must use createResource
method
;;
After resource creation, set properties
resource.name = "my resource";resource.owner = owner;
Call create
method
;
if your server return new created object, create return this object. createdResource have type Resource. create don't populate the existing object.
Configuration
request configuration
You can configure some parameter on you client. HalClient use axios to run ajax request.
You can configure each parameter describe here
To do, you have two solution:
// example to configure CORS withCredentials parametercreateClient'http://test.fr', // orclient.config.withCredentials = true
interceptor
You can configure interceptors, you have two interceptor types :
- request interceptor : configure request information
- response interceptor: do something with server response. This interceptor is called before object parsing to HalResource
// Add a request interceptorhalClient.interceptors.request.use, ; // Add a response interceptorhalClient.interceptors.response.use, ;
API description
Client creation
Two parameters can be used for create a client.
- The base URI. fetchs are done with this base
- A header. All request are done with this header
an base URL can be used to fetch resources.
;;
header can be set to HalRestClient
;// or;client.addHeader'authorization', 'Basic Auth';
When the client fetch a resource, a parser is used to convert json on HalResource. You can customize the parsing method. To do this, you need extends JSONParser and implements your own jsonToResource method. After, you can set the parser like this.
client.setJsonParsermyParser;
HalProperty
HalProperty
annotation is used to map model with service body.
HalProperty have two parameters:
- name of property on service body. default it's the same name
- type. model to use for embedded or link.
Fetch
fetchResource
Fetch a service, and return an HalResource. Parameter is the URI.
client.fetchResource'/resources/5';// orclient.fetchResource'http://test.fr/resources/5';
fetch
Fetch a service and return a model class. Parameter is the URI and model class.
client.fetch'/resources/5', Resource;// orclient.fetch'http://test.fr/resources/5', Resource;
fetchArray
Fetch an array service. Return an array of object (HalResource or model class). The service can return :
- A simple array of HAL resources
- A HAL resource containing a list of HAL resource on _embedded
client.fetchArray'/resources', Resource;// orclient.fetchArray'http://test.fr/resources', Resource;// orclient.fetchArray'http://test.fr/resources', HalResource;
Create or update HAL Resource
To create or update resource, Typescript Objects are serialized on simple json to send at server.
on create
or update
method you can use custom JsonSerializer.
;
- parseProp : parse a simple property (not an HalResource)
- parseResource : parse a HalResource or model class