Microshare HTTP API

Introduction

Welcome to Microshare’s API documentation!

This API allows you to create and manage your data within Microshare’s data lake.

  • With Shares, you’ll be able to directly create, search, retrieve and delete data.

To quickly get started, click on the button below to run the Microshare collection in Postman:

Or manually download and import the collection and the environment to your Postman.

API structures

Shares

Shares represent your data stored in Microshare's data lake

recType string Record type using the dot notation format (eg. io.microshare.test)
id ObjectId An auto-generated unique identifier for the share
data JSON Object The data object is where your data is stored in our data lake

Authentication

Request and revoke tokens used to authenticate to our API

POST Request Token

https://auth.microshare.io/oauth2/token?username={{username}}&password={{password}}&client_id={{apikey}}&grant_type=password&scope=ALL:ALL

Request an Authentification token required to use this API.

You will need to provide username, password, as well as a valid API Key. You can manage your API keys in our Keys Console.

The default scope is ALL:ALL, but you can replace it to request tokens that will allow limited operations. For example, if the scope is SHARE:READ the token will only allow you to read Shares.

Sample Request
curl -X POST -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" "https://auth.microshare.io/oauth2/token?username={{username}}&password={{password}}&client_id={{apikey}}&grant_type=password&scope=ALL:ALL"
POST /oauth2/token?username={{username}}&password={{password}}&client_id={{apikey}}&grant_type=password&scope=ALL:ALL HTTP/1.1
Host: auth.microshare.io

Shares

Upload your data and easily share it with the Share API

GET Get one Share

https://api.microshare.io/share/:recType/:id

Retrieve one share by recType and object id

Sample Request
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.microshare.io/share/:recType/:id"
GET /share/:recType/:id HTTP/1.1
Host: api.microshare.io
Authorization: Bearer {{token}}
Sample Response
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:15:41 GMT
status 200 
{
    "meta": {
        "totalPages": 1,
        "currentPage": 1,
        "perPage": 999,
        "totalCount": 1,
        "currentCount": 1
    },
    "objs": [
        {
            "updaterId": "your@email.com",
            "desc": "",
            "name": "",
            "createDate": {
                "$date": 1495501715141
            },
            "_id": {
                "$oid": "59238b9346e0fb0352c29???"
            },
            "data": {
                "hello": "world"
            },
            "creatorId": "your@email.com",
            "id": "59238b9346e0fb0352c29???",
            "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
            "tstamp": {
                "$numberLong": "1495501715141"
            },
            "origin": {
                "tokendata": {
                    "ip": "your ip address",
                    "id": "0d540f05-0dd9-4a78-b8b4-00416404????"
                },
                "desc": "Object of Type io.microshare.test",
                "name": "io.microshare.test",
                "createDate": {
                    "$numberLong": "1495501715141"
                },
                "creatorId": "your@email.com",
                "id": "59238b9346e0fb0352c29???",
                "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
                "remoteAddress": "your remote address"
            },
            "recType": "io.microshare.test",
            "owner": {
                "appid": "2FA9DF02-F4EC-4DA4-AEC1-0508E228????",
                "org": "io.point",
                "user": "your@email.com"
            }
        }
    ]
}

GET Get Shares by recType

https://api.microshare.io/share/:recType?details=false&page=1&perPage=999&sort=name

Retrieve all shares under a specific recType

Query parameters available
Parameter Type Description
details boolean true will return matching objects with their details, false will only return main information
page int Specifies the requested page, defaults to 1
perPage int Specifies the number of objects to be returned per page, defaults to 999
sort string Specifies a comma-delimited list of field names to apply ascending alphabetical (0-9a-z) sorting
eg. &sort=name &sort=name,tstamp &sort=data.priority
Sample Request
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.microshare.io/share/:recType?details=false&page=1&perPage=999&sort=name"
GET /share/:recType?details=false&page=1&perPage=999&sort=name HTTP/1.1
Host: api.microshare.io
Authorization: Bearer {{token}}
Sample Response
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:19:00 GMT
status 200 
{
    "meta": {
        "totalPages": 1,
        "currentPage": 1,
        "perPage": 999,
        "totalCount": 2,
        "currentCount": 2
    },
    "objs": [
        {
            "updaterId": "your@email.com",
            "desc": "",
            "name": "",
            "createDate": {
                "$date": 1495501715141
            },
            "_id": {
                "$oid": "59238b9346e0fb0352c29???"
            },
            "data": {
                "hello": "world"
            },
            "creatorId": "your@email.com",
            "id": "59238b9346e0fb0352c29???",
            "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
            "tstamp": {
                "$numberLong": "1495501715141"
            },
            "origin": {
                "tokendata": {
                    "ip": "your ip address",
                    "id": "0d540f05-0dd9-4a78-b8b4-00416404????"
                },
                "desc": "Object of Type io.microshare.test",
                "name": "io.microshare.test",
                "createDate": {
                    "$numberLong": "1495501715141"
                },
                "creatorId": "your@email.com",
                "id": "59238b9346e0fb0352c29???",
                "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
                "remoteAddress": "your remote address"
            },
            "recType": "io.microshare.test",
            "owner": {
                "appid": "2FA9DF02-F4EC-4DA4-AEC1-0508E228????",
                "org": "io.point",
                "user": "your@email.com"
            }
        },
        {
            "updaterId": "your@email.com",
            "desc": "",
            "name": "",
            "createDate": {
                "$date": 1495502001213
            },
            "_id": {
                "$oid": "59238cb146e0fb0352c29???"
            },
            "tags": [
                "foo",
                "bar"
            ],
            "data": {
                "hello": "world"
            },
            "creatorId": "your@email.com",
            "id": "59238cb146e0fb0352c29???",
            "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
            "tstamp": {
                "$numberLong": "1495502001213"
            },
            "origin": {
                "tokendata": {
                    "ip": "your ip address",
                    "id": "0d540f05-0dd9-4a78-b8b4-00416404????"
                },
                "desc": "Object of Type io.microshare.test",
                "name": "io.microshare.test",
                "createDate": {
                    "$numberLong": "1495502001213"
                },
                "creatorId": "your@email.com",
                "id": "59238cb146e0fb0352c29???",
                "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
                "remoteAddress": "your remote address"
            },
            "recType": "io.microshare.test",
            "owner": {
                "appid": "2FA9DF02-F4EC-4DA4-AEC1-0508E228????",
                "org": "io.point",
                "user": "your@email.com"
            }
        }
    ]
}
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:19:37 GMT
status 200 
{
    "meta": {
        "totalPages": 1,
        "currentPage": 1,
        "perPage": 999,
        "totalCount": 2,
        "currentCount": 2
    },
    "objs": [
        {
            "name": "",
            "url": "/share/io.microshare.test/59238b9346e0fb0352c2948b",
            "_id": {
                "$oid": "59238b9346e0fb0352c29???"
            },
            "id": "59238b9346e0fb0352c29???",
            "tstamp": "05/23/2017 01:08:35:141 AM",
            "recType": "io.microshare.test"
        },
        {
            "name": "",
            "url": "/share/io.microshare.test/59238cb146e0fb0352c2948e",
            "_id": {
                "$oid": "59238cb146e0fb0352c29???"
            },
            "tags": [
                "foo",
                "bar"
            ],
            "id": "59238cb146e0fb0352c29???",
            "tstamp": "05/23/2017 01:13:21:213 AM",
            "recType": "io.microshare.test"
        }
    ]
}

GET Get Shares by Tags and recType

https://api.microshare.io/share/:recType/tags/:tag1/:tag2?details=false&page=1&perPage=999&sort=name

Retrieve all shares under a specific recType and containing one or several tags. Specify as many tags as you need, and objects containing all of these tags will be returned.

Query parameters available
Parameter Type Description
details boolean true will return matching objects with their details, false will only return main information
page int Specifies the requested page, defaults to 1
perPage int Specifies the number of objects to be returned per page, defaults to 999
sort string Specifies a comma-delimited list of field names to apply ascending alphabetical (0-9a-z) sorting
eg. &sort=name &sort=name,tstamp &sort=data.priority
Sample Request
curl -X GET -H "Authorization: Bearer {{token}}" "https://api.microshare.io/share/:recType/tags/:tag1/:tag2?details=false&page=1&perPage=999&sort=name"
GET /share/:recType/tags/:tag1/:tag2?details=false&page=1&perPage=999&sort=name HTTP/1.1
Host: api.microshare.io
Authorization: Bearer {{token}}
Sample Response
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:29:23 GMT
status 200 
{
    "meta": {
        "totalPages": 1,
        "currentPage": 1,
        "perPage": 999,
        "totalCount": 1,
        "currentCount": 1
    },
    "objs": [
        {
            "updaterId": "your@email.com",
            "desc": "",
            "name": "",
            "createDate": {
                "$date": 1495502001213
            },
            "_id": {
                "$oid": "59238cb146e0fb0352c29???"
            },
            "tags": [
                "foo",
                "bar"
            ],
            "data": {
                "hello": "world"
            },
            "creatorId": "your@email.com",
            "id": "59238cb146e0fb0352c29???",
            "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
            "tstamp": {
                "$numberLong": "1495502001213"
            },
            "origin": {
                "tokendata": {
                    "ip": "your ip address",
                    "id": "0d540f05-0dd9-4a78-b8b4-00416404????"
                },
                "desc": "Object of Type io.microshare.test",
                "name": "io.microshare.test",
                "createDate": {
                    "$numberLong": "1495502001213"
                },
                "creatorId": "your@email.com",
                "id": "59238cb146e0fb0352c29???",
                "checksum": "93A23971A914E5EACBF0A8D25154CDA309C3C1C72FBB9914D47C60F3CB681588L17",
                "remoteAddress": "your remote address"
            },
            "recType": "io.microshare.test",
            "owner": {
                "appid": "2FA9DF02-F4EC-4DA4-AEC1-0508E228????",
                "org": "io.point",
                "user": "your@email.com"
            }
        }
    ]
}
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:29:41 GMT
status 200 
{
    "meta": {
        "totalPages": 1,
        "currentPage": 1,
        "perPage": 999,
        "totalCount": 1,
        "currentCount": 1
    },
    "objs": [
        {
            "name": "",
            "url": "/share/io.microshare.test/59238cb146e0fb0352c2948e",
            "_id": {
                "$oid": "59238cb146e0fb0352c29???"
            },
            "tags": [
                "foo",
                "bar"
            ],
            "id": "59238cb146e0fb0352c29???",
            "tstamp": "05/23/2017 01:13:21:213 AM",
            "recType": "io.microshare.test"
        }
    ]
}

POST Create one Share

https://api.microshare.io/share/:recType

Create a new share by recType. This inserts a new record into the Microshare data lake.

You must include a record type using the dot notation format (eg. io.microshare.test).

Sample Request
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {{token}}" -d '{
    "hello": "world"
}' "https://api.microshare.io/share/:recType"
POST /share/:recType HTTP/1.1
Host: api.microshare.io
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "hello": "world"
}
Sample Response
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:08:35 GMT
status 200 
{
    "meta": {
        "totalPages": 0,
        "currentPage": 1,
        "perPage": 0,
        "totalCount": 1,
        "currentCount": 1
    },
    "objs": [
        {
            "name": "",
            "url": "/share/io.microshare.test/59238b9346e0fb0352c2948b",
            "_id": {
                "$oid": "59238b9346e0fb0352c29???"
            },
            "id": "59238b9346e0fb0352c29???",
            "tstamp": "05/23/2017 01:08:35:141 AM",
            "recType": "io.microshare.test"
        }
    ]
}

POST Create one Share with Tags

https://api.microshare.io/share/:recType/tags/:tag1/:tag2

Create a new share by recType, with searchable tags. This inserts a new record into the Microshare data lake.

You must include a record type using the dot notation format (eg. io.microshare.test).

Tags allow you to later search objects with the same recType with a GET request. You can specify as many tags as you need.

Sample Request
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {{token}}" -d '{
	"hello": "world"
}' "https://api.microshare.io/share/:recType/tags/:tag1/:tag2"
POST /share/:recType/tags/:tag1/:tag2 HTTP/1.1
Host: api.microshare.io
Content-Type: application/json
Authorization: Bearer {{token}}

{
	"hello": "world"
}
Sample Response
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:13:21 GMT
status 200 
{
    "meta": {
        "totalPages": 0,
        "currentPage": 1,
        "perPage": 0,
        "totalCount": 1,
        "currentCount": 1
    },
    "objs": [
        {
            "name": "",
            "url": "/share/io.microshare.test/59238cb146e0fb0352c2948e",
            "_id": {
                "$oid": "59238cb146e0fb0352c29???"
            },
            "tags": [
                "foo",
                "bar"
            ],
            "id": "59238cb146e0fb0352c29???",
            "tstamp": "05/23/2017 01:13:21:213 AM",
            "recType": "io.microshare.test"
        }
    ]
}

DELETE Delete one Share

https://api.microshare.io/share/:recType/:id

Permanently delete one share by recType and object id

Sample Request
curl -X DELETE -H "Authorization: Bearer {{token}}" "https://api.microshare.io/share/:recType/:id"
DELETE /share/:recType/:id HTTP/1.1
Host: api.microshare.io
Authorization: Bearer {{token}}
Sample Response
Status 200 OK
content-encoding gzip
content-type application/json
date Tue, 23 May 2017 01:18:55 GMT
status 200 
{
    "meta": {
        "totalPages": 0,
        "currentPage": 1,
        "perPage": 0,
        "totalCount": 1,
        "currentCount": 1
    },
    "objs": [
        {
            "id": "592331ce46e0fb0352c29???",
            "recType": "io.microshare.test"
        }
    ]
}