Outbound API (deprecated)
The outbound API is deprecated and will be removed in a future version of WorkAdventure. Do not use it for new projects.
Why
The major interest in developing your own admin API is to integrate WorkAdventure into an existing computer system. Rather than trying to synchronize your list of members and rooms with WorkAdventure, WorkAdventure will directly fetch the list of members and rooms from your application, in real-time.
Architecture
When you use the Outbound API, WorkAdventure will completely bypass its internal database. Instead, each time a user connects to WorkAdventure, it will perform several queries to your application to know where to route your user and to check if your user is allowed to connect.
This means that your own application replaces the WorkAdventure administration dashboard.
If you only want to edit the list of members and still want to use the WorkAdventure administration dashboard to manage rooms, take a look at our more classical REST API instead.
Principles
When implementing the Outbound API, it is important to understand that it is not your site that will call the API but the opposite!
When you define access to your Outbound API, WorkAdventure will directly ask your application for the information and authorizations it needs.
These are the 2 end points that are the most important :
/api/mapinformation
On the sequence diagram this is the call n°1.
This end point returns an object mapping a room URL to the file name of the map. It will process the playURI and the uuid to return the information of the map if the user can access it.
In case of success, this endpoint returns aMapDetailsDataobject./api/roomaccess
On the sequence diagram this is the call n°3.
This end point returns the member's information if he can access this room.
In case of success, this endpoint returns aFetchMemberDataByUuidResponseobject.
What to do
- You will need to implement, in your website, all the URLs that are listed in this swagger documentation : Outbound API documentation.
- Define your outbound API in the admin of WorkAdventure.
Screenshot of API settings set to activated - Go to Settings > Developers.
- In the "API settings" set the toggle 'OutBound API activated' to true.
- Fill the input with the URL of your API.
- Then save your changes. - Authentication
Authentication will be done with a token present in the header when we come to question your API. This token will be provided by WorkAdventure in your Back Office. To set this token :- Go to Settings > Developers.
- In the "Tokens" sections, click on 'Create new token?'.
- Fill the input with the name you want of your token.
- Save the token for the next step.
- Checking access right to your API
You will need to check the token. WorkAdventure will put the token in the HTTP header of each call made to your API.Authorization: <token>
If the token is wrong, you should return an authorization error with HTTP code 401. - You are done. 🚀
- If you want to be sure that everything is working you can check the logs.
Screenshot of API settings set to activated - Go to Settings > Developers.
- In the "Logs" section you will see all the calls make to your outbound API.