Quick start tutorial: Securing a RESTful API
Estimated time to complete: 4-5 minutes
There are times you when you must secure your API in order to protect sensitive resources and services. On this tutorial page, you'll learn how to secure your Gloop REST API by using the Security tab of the Gloop REST API editor.
Create users and groups
Martini implements security through users and groups. However, before you can begin specifying permissible users and groups in your Gloop REST API, they must first exist in Martini.
To add a user:
- Open the Users and Groups dialog by right clicking on your instance, and then select Users and Groups from the context menu.
- Select the Users tab.
- Click the green, '+'-labeled button.
- Provide the new user's details in the appearing form (making sure it's enabled).
- Click Save.
- In Martini Desktop, click the OK button to close the dialog once done.
Groups are added in a similar fashion, but in the Groups tab.
Specify authorized users and groups
With users and/or groups created, you can set permissions in an API. To do this:
- Open the Gloop REST API by double clicking it in the Navigator if it's not already open.
- Select the Security tab.
- Check OAuth 2.0 as the Authentication Type.
- Add permissible users or groups using the green, '+'-labeled button.
- Press (or by pressing the save button in the main toolbar) to save your changes.
Invoke the secured API using the HTTP Client
With your API secured, callers must now send requests with credentials so Martini doesn't reject them. This applies to all operations defined under the secured Gloop REST API.
To test if the permissions you've set are implemented as expected, use Martini Desktop's HTTP Client. Because it's integrated in the IDE, it's very easy to generate a request for a Gloop REST API operation. To do this:
- Right click on the operation in the Operations tab.
- Select Invoke in HTTP Client from the appearing context menu.
First, try sending a request without credentials. Doing this will prompt Martini to return a 401 (Unauthorized) response.
Now, try sending it with credentials.
- Go to the HTTP Client's Authentication tab.
- Select Oauth 2.0 as the type.
- Provide the credentials of the user you'll be using to send the request. Providing the OAuth 2.0 credentials is explained below.
Getting OAuth 2.0 details to invoke the operation securely
The Gloop REST API used in this tutorial is configured to implement only OAuth 2.0. This should be specified in the request; which also means the user's access token must be provided. One way to copy the access token of an authorized user is through the following steps:
- Open the Gloop REST API.
- Click on the Security tab.
- Right-click the user you want to use, then select Copy Access Token from the appearing context menu.
- In the HTTP Client, click on the Authentication tab.
- Choose OAuth 2.0 as the Type, then paste the access token into the Access Token field.
With the HTTP client now configured to send the relevant OAuth details in the request, you will now be able to invoke the secured API operation.