Rest API with authentication

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.

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:

Hidden Content

Give reaction to this post to see the hidden content.

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

Hidden Content

Give reaction to this post to see the hidden content.

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:

Hidden Content

Give reaction to this post to see the hidden content.

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

Hidden Content

Give reaction to this post to see the hidden content.

Your result will be something like that:

Hidden Content

Give reaction to this post to see the hidden content.

Make authorized requests

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

Hidden Content

Give reaction to this post to see the hidden content.

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

Hidden Content

Give reaction to this post to see the hidden content.

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: