Rest API Slides

MIIMETIQ API TRAINING
A powerful and RESTFul API

What we'll cover today
● Authentication via JWT ● Batching

● Info endpoint ● Projections
● HATEOAS and METADATA ● Embeds
● Resources GET, POST, DELETE ● Pagination
● Concurrency Control ● Sorting
● Items GET, PUT, PATCH, DELETE ● Filtering
Main MIIMETIQ API endpoints
● /assets
● /schemas
● /locations
Authentication via JWT
MIIMETIQ API uses JSON Web Token: A standard that defines a compact and self-
contained way for securely transmitting information between parties as a JSON object.
Tokens consist of three Base64-URL strings separated by dots:
● Header
● Payload
● Signature
Use the endpoint "authn/login" to create a new session.
$ curl -X POST 'http://api.miimetiq.local/authn/login'

-H 'Content-Type: application/json'
--data-binary '{"username":"foo","password":"bar"}'
After a successful login the JSON Web Token is returned by the server.
{
"token": "eyJhbGciOiJIUzI1NiIsE4fQ.eWxNy1QVpDQus (...) 6XbIdj7kiMTQ2LTR.y7Ld1hKpmGPMBiJrw03Jr1ejaNfw",
"success": true
}
The token must be provided in the subsequent requests using the header Access-Token
Use the endpoint "authn/logout" to close the current session.
$ curl -X GET 'http://api.miimetiq.local/authn/logout'

-H 'Access-Token: eyJhbGciOiJIUzI1NE4fQ.eWxNy1QVpDQus (...) 6XbIdj7kiMTQ2LTR.y7Ld1hKpmGPMBiJrw03Nfw'
{
"success": true
}
Info endpoint
Use the endpoint "authn/info" to get the information of the current session.
$ curl -X GET 'http://api.miimetiq.local/authn/info'

{
"username": "foo",
"first_name": "",
"last_name": "",
(...)
"groups": [],
"active": true,
"mail": null,
"is_viewer": false
}
HATEOAS and METADATA
Hypermedia As The Engine Of Application State (HATEOAS) is a mechanism for the client
to dynamically discover information about the API.
The _links property provides information about the resource tree:
"_links": {
"self": {
"href": "assets/demo-asset",
"title": "assets/demo-asset"
},
"parent": {
"href": "/",
"title": "home"
}
}
HATEOAS and METADATA
Hypermedia As The Engine Of Application State (HATEOAS) is a mechanism for the client
to dynamically discover information about the API.
The _meta property provides information about the current resource:
"_meta": {
"max_results": 100,
"total": 0,
"page": 1
}
Resources GET, POST, DELETE
Each model (or schema) installed in MIIMETIQ is accessible as a resource in the API.
The items (or assets) of a resource can be managed at the resource URL.
http://api.{domain}/assets/{model}
The following HTTP methods are available per resource:
● GET > To fetch the items in the resource

● POST > To create new items in the resource
● DELETE > To delete the items in the resource
To get all the items from a resource / all the assets from a model:
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset'

{
"_total": 0,
"_items": [...],
"_links": {...},
"_meta": {...}
}
To create a new item:
$ curl -X POST 'http://api.miimetiq.local/assets/demo-asset'

--data-binary '{"name":"foo"}'
To create a new item:
{
"_updated": "2019-05-30T05:37:45Z",
"_links": {
"self": {
"href": "assets/demo-asset/5cef6c291d6543004d433841",
"title": "Demo-asset"
}
},
"_created": "2019-05-30T05:37:45Z",
"_status": "OK", The _id and the _etag are provided in the response
"_id": "5cef6c291d6543004d433841", so further edition can be done right away
"_etag": "ef765215879a96a2c627a98c96e714e582bd7d2f"
}
To delete all the assets in a resource:
$ curl -X DELETE 'http://api.miimetiq.local/assets/demo-asset'

Be extremely careful with this. All the

assets will be deleted permanently
Concurrency Control
Etags are stored in the assets automatically and change every time the asset is modified.
An Etag looks like this:
2aa8283707eb5452cc5891ab3ffb6489441360a1
Etags are used in combination with the If-Match header: When two or more clients
attempt to update a resource at the same time, the provided Etag lets the server decide if the
resource should be updated. Only the client providing the valid (current) Etag is allowed to
modify the document.
Without any concurrency checks, the client who submits changes last, wins, and that can
break things in unexpected and unnoticed ways.
Items GET, PUT, PATCH, DELETE
An item (or asset) can be managed at the item URL.
http://api.{domain}/assets/{model}/{objectID}
The following HTTP methods are available per item:
● GET > To fetch the item

● PUT > To overwrite the item
● PATCH > To modify the item
● DELETE > To delete the item
To get a single the item or asset:
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

{
tracks the last edition date
"_updated": "2019-05-30T05:37:45Z",
HATEOAS provides info
"name": "demo1",
about the resource name of the model
"__type__": "demo-asset",
tree
"_user": "amAdmin",
"_links": {
"self": { "href": "assets/demo-asset/5cef6c291d6543004d433841", "title": "Demo-asset" },
"collection": { "href": "assets/demo-asset", "title": "assets/demo-asset" },
"parent": { "href": "/", "title": "home" }
}, creation date of the document
"_created": "2019-05-30T05:37:45Z",
"_group": null, unique identifier of the
"_id": "5cef6c291d6543004d433841", document concurrency
"_etag": "ef765215879a96a2c627a98c96e714e582bd7d2f" control
}
To overwrite a single the item or asset:
$ curl -X PUT 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

--data-binary '{"name":"bar"}'
-H 'If-Match: ef765215879a96a2c627a98c96e714e582bd7d2f'

Remember that for PUT, PATCH and DELETE the _etag

must be provided using the If-Match header

Note that all the required and desired fields must be

provided when using PUT to overwrite an asset
{
"_updated": "2019-05-30T09:31:46Z",
"_links": {
"self": {
"href": "assets/demo-asset/5cefa2641d6543004f433841",
}
},
"_created": "2019-05-30T09:29:08Z",
"_status": "OK",
"_id": "5cefa2641d6543004f433841",
"_etag": "a436c1493a4ffc0fbe1477b15bec16bb3152f69c"
}
To modify a single the item or asset:
$ curl -X PATCH 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

To modify a single the item or asset:
{
"_updated": "2019-05-30T09:31:46Z",
"_links": {
"self": {
"href": "assets/demo-asset/5cefa2641d6543004f433841",
}
},
"_created": "2019-05-30T09:29:08Z",
"_status": "OK",
"_id": "5cefa2641d6543004f433841",
"_etag": "a436c1493a4ffc0fbe1477b15bec16bb3152f69c"
}
To delete a single the item or asset:
$ curl -X DELETE 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

Batching
MIIMETIQ API supports bulk inserts in order to reduce the number of requests.
A client can submit multiple documents with a single request enclosing the documents in a
JSON list.
$ curl -X POST 'http://api.miimetiq.local/assets/demo-asset'

--data-binary '[{"name":"foo"}, {"name":"bar"}, {"name":"baz"}]'
Batching
The response will be a list itself, with the state of each document:
{
"_status": "OK",
"_items": [
{
"_updated": "2019-05-30T11:10:28Z",
"_links": {...},
"_created": "2019-05-30T11:10:28Z",
"_status": "OK",
"_id": "5cefba241d6543004f433844",
"_etag": "0a37c11945691743335f83f5857b1c89964b72bf"
},
...
...
]
}
Projections
Projections allow clients to create dynamic views of collections and documents by deciding
which fields should or should not be returned.
The use of queries in which the client determines which fields the API should return allows
to save bandwidth and improves the user experience.
Projections apply both to resources and single items.
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?projection={"name": 1}'

Embeds
When an asset is related or referenced in another asset, clients can request the referenced
document to be embedded within the requested document.
Clients have the power to activate document embedding on per-request basis by means of a
query parameter.
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset-child?embedded={"parent": 1}'

Pagination
Resource pagination allows to preserve bandwidth while improving performance and the
user experience.
When a consumer requests a resource, the first N items matching the query are served, and
links to subsequent/previous pages are provided with the response. Default and maximum
page size is customizable, and consumers can request specific pages via the query string.
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?max_results=20&page=1'

Sorting
Sorting the returned documents is also possible using the sort parameter.
It's possible to decide the sort order for a field by adding 1 or -1 for to reverse the order.
The following query would return the documents sorted by name (descending).
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?sort=[("name", -1)]'

Filtering
The documents in a resource endpoint can be filtered using mongoDB query syntax.
Advanced queries can be built by nesting and combining conditional and logical operators
as:
● Comparison: $eq, $gt, $gte, $in, $lt, $lte, $ne, $nin

● Logical: $and, $not, $nor, $or
● Element: $exists, $type
● Geospatial: $geoIntersects, $geoWithin, $near, $nearSphere
● Array: $all, $elemMatch, $size
Refer to mongoDB docs:

Filtering
The queries are built using the query string param where. Let's see some examples:
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?where={"name": "Jane"}'

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?where={"$and":[{"name": "Jane"},

{"surname": "Doe"}]}'
$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?

where={"$and":[ {"active_date":{"$gt":"2019-05-30T11:00:00Z"},"active_date":{"$lt":"2019-05-30T12:00:00Z"}}
]}
'
Thank you!

Rest API Slides

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Rest API Slides

Uploaded by

Copyright:

Available Formats

MIIMETIQ API TRAINING

A powerful and RESTFul API

● Authentication via JWT ● Batching

Tokens consist of three Base64-URL strings separated by dots:

$ curl -X POST 'http://api.miimetiq.local/authn/login'

$ curl -X GET 'http://api.miimetiq.local/authn/logout'

$ curl -X GET 'http://api.miimetiq.local/authn/info'

The _links property provides information about the resource tree:

The _meta property provides information about the current resource:

The following HTTP methods are available per resource:

● GET > To fetch the items in the resource

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset'

$ curl -X POST 'http://api.miimetiq.local/assets/demo-asset'

$ curl -X DELETE 'http://api.miimetiq.local/assets/demo-asset'

Be extremely careful with this. All the

An Etag looks like this:

The following HTTP methods are available per item:

● GET > To fetch the item

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

$ curl -X PUT 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

$ curl -X PUT 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

Remember that for PUT, PATCH and DELETE the _etag

$ curl -X PUT 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

Note that all the required and desired fields must be

$ curl -X PATCH 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

$ curl -X DELETE 'http://api.miimetiq.local/assets/demo-asset/{objectId}'

$ curl -X POST 'http://api.miimetiq.local/assets/demo-asset'

Projections apply both to resources and single items.

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?projection={"name": 1}'

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset-child?embedded={"parent": 1}'

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?max_results=20&page=1'

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?sort=[("name", -1)]'

● Comparison: $eq, $gt, $gte, $in, $lt, $lte, $ne, $nin

Refer to mongoDB docs:

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?where={"name": "Jane"}'

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?where={"$and":[{"name": "Jane"},

$ curl -X GET 'http://api.miimetiq.local/assets/demo-asset?

You might also like