[IPS Marketplace] (itzrest) Rest API with authentication

[NewsBot]

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

• Install the application through uploading it in the ACP
• Navigate to "Community" > "Itzrest" > "Settings" and insert a random 32 length key. This step is only needed if you want to use authorized access to the API. The key will be used to encode user tokens and authenticate the user if you make API calls.
• Make sure your webserver supports authentication headers. Otherwise authorized access will not work.
• That's it. Everything should work like a charme right now. Go on with the next topics

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".

• Forums
  • /forums
  • /forums/<forumId>
  • /forums/<forumId>/topics
  • /forums/posts
  • /forums/posts/<postId>
  • /forums/topics
  • /forums/topics/<topicId>
  • /forums/topics/<topicId>/posts
• Core
  • /discover/unread
  • /discover
  • /reactions
  • /reactions/<reactionId>
  • /staff/users
  • /staff/users/<userId>
  • /staff/groups
  • /staff/groups/<groupId>
  • /messenger/folders
  • /messenger/folders/<folderId>
  • /messenger/folders/<folderId>/conversations
  • /messenger/conversations
  • /messenger/conversations/<conversationId>
  • /messenger/conversations/<conversationId>/messages
  • /messenger/messages
  • /messenger/messages/<messageId>
• Calendar
  • /calendars
  • /calendars/<calendarId>
  • /calendars/<calendarId>/comments
  • /calendars/<calendarId>/events
  • /calendars/comments
  • /calendars/comments/<commentId>
  • /calendars/events
  • /calendars/events/<eventId>
  • /calendars/events/<eventId>/reviews
  • /calendars/events/<eventId>/comments
  • /calendars/reviews
  • /calendars/reviews/<reviewId>
• Gallery
  • /gallery/albums
  • /gallery/albums/<albumId>
  • /gallery/albums/<albumId>/images
  • /gallery/albums/<albumId>/comments
  • /gallery/categories
  • /gallery/categories/<categoryId>
  • /gallery/categories/<categoryId>/images
  • /gallery/categories/<categoryId>/albums
  • /gallery/reviews
  • /gallery/reviews/<reviewId>
  • /gallery/comments
  • /gallery/comments/<commentId>
  • /gallery/images
  • /gallery/images/<imageId>
  • /gallery/images/<imageId>/comments
• Authentication
  • /auth/login
  • /auth/authenticate

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"
        }
    }
}

 

View the full article