(itzrest) Rest API with authentication > Invisionize.eu - IP.Board (IPB) News
Kanał Rss Kanał Rss
Kanał Atom Kanał Atom

(itzrest) Rest API with authentication

wersja drukowalna wersja Microsoft Word wersja HTML

For one of my projects I needed the possibility to read data from my board. I could not use the built in API because one important thing still is missing: user authentication and only get data the user is allowed to read. So I wrote my own REST API, including user authentication with tokens and a fluent data output. Currently it is not possible to write data. But the plan is to implement that feature in the future.

The plugin is currently in a beta state and available for free. In the future there a plans that you have to purchase it.

Installation

Implemented endpoints

Currently the following endpoints are implemented (more will be available in the future). And again: at the moment it is only possible to read data. You must prefix every endpoint with /restapi".

Login as user

To login as a user you must send a POST Request to the /auth/login endpoint with your username and password:

curl 
    -d username=max
    -d password=secret
    -X POST <baseurl>/restapi/auth/login

As result you will get an object with several user data and the most important thing: the access token:

{
    "data": {
        "id": "1",
        "name": "max",
        "access_token": "********",
        "photoUrl": "",
        "birthday": ""
    }
}

Keep the token secret and use it for authorized API calls how described in the step "make authorized requests". If you use authentication it would be the best way if you use a secure (https) connection to make API calls.

Make requests

Nothing more than sending a GET request to a specific endpoint:

curl <baseurl>/restapi/<endpoint>

For example: If you want to have all available calendars from your board:

curl POST <baseurl>/restapi/calendars

Your result will be something like that:

{
    "data": [
        {
            "id": "1",
            "title": "Community Calendar",
            "title_seo": "community-calendar",
            "color": "#6E4F99"
        }
    ]
}

Make authorized requests

For authorized requests you need an access token. Append the access token as authorization header and make your request:

curl 
    -H "Authorization: Bearer <token>" 
    -X <baseurl>/restapi/forums

You can validate if your token is valid by sending a request to the /auth/authenticate endpoint:

curl 
    -H "Authorization: Bearer <token>" 
    -X POST <baseurl>/restapi/auth/authenticate

As result you should get a valid user object.

Pagination, order

If your board has thounsands of posts or threads we must paginate the results. Otherwise the performance of your requests will be horrible. Each endpoint accepts query parameters to sort and paginate your results in an easy way. Therefore each endpoint has a meta node in its result whicht give you information about your current agination state:

"meta": {
    "pagination": {
        "total": "22",
        "count": "22",
        "per_page": "25",
        "current_page": "1",
        "total_pages": "1",
        "links": []
    }
}

Now let us filter / paginate and limit our results:

curl <baseurl>/restapi/forums/2/topics?order=title&orderDirection=asc&limit=5&page=2

We will get the following meta output:

"meta": {
    "pagination": {
        "total": "22",
        "count": "5",
        "per_page": "5",
        "current_page": "2",
        "total_pages": "5",
        "links": {
            "previous": "<baseurl>/restapi/forums/2/topics/?page=1&order=title&orderDirection=asc&limit=5",
            "next": "<baseurl>/restapi/forums/2/topics/?page=3&order=title&orderDirection=asc&limit=5"
        }
    }
}

 

czw, 19 październik 2017