REST APIs - What and Why?
- Ayesha Dissanayaka
- Senior Technical Lead - WSO2
REpresentational State Transfer (REST) is an architectural style for designing APIs; it provides a set of standards that makes it easier for systems to communicate with each other.
REST APIs for core management capabilities and end-user interactions are becoming essential for building both on-premises and cloud-based solutions. RESTful APIs are more flexible, faster, popular, and scalable. They are now favored over SOAP APIs, which are becoming outdated.
The WSO2 IAM team is in the process of making all the functionalities of WSO2 Identity Server available via RESTful APIs in a unified manner. Also, we are building a brand-new set of portals for the end-user and identity developer, as well as for administrator interactions, which will be backed by the newly onboarded REST APIs.
All REST API schemas are defined as Swagger-2.0 documents. This makes APIs easy to understand and consume and has the advantage of inherent SDK support that comes with Swagger. Identity developers may use a technology of their own choice to consume these APIs and generate clients easily using the Swagger definition.
User Self-service APIs
In an IAM solution, users and their accounts are the center of attention. Self-service activities are commonly and frequently exercised use cases in those systems. These endpoints are dedicated to managing user resources and providing capabilities to perform on end-user accounts.
E.g.,
- The user’s security questions and answers
- The user’s associated accounts
- The user’s authenticated sessions
Base path: /t/{tenant-domain}/api/user/{version}/me/
APIs for Administrators
Server-based APIs
The server itself holds resources and metadata that are the building blocks of the IAM solution. These API endpoints can be used to manage the resources of the server itself.
E.g.,
- Challenge questions
- Email templates
- Claim dialects
Base path: /t/{tenant-domain}/api/server/{version}/
API Versioning
The version of an API is specified as part of its URI and only the major versions of APIs will be reflected in the URI. The major version of an API is released only when a breaking change to an existing schema or endpoint is introduced, or when a major upgrade is introduced into the APIs. Minor changes such as attribute additions, endpoint additions, or additions of HTTP verbs to an existing endpoint will not be reflected via a major API version change.
Authentication and Authorization for APIs
There are three ways of authenticating to APIs:
- Basic authentication: Use the user’s credentials in the API invocation
- OAuth 2 common flows: Obtain a token using an oauth2 flow and use the token when invoking the API
- Client certificate-based: Use Mutual SSL to authenticate in order to consume the APIs
Unless one of the above authentication elements is sent in an API invocation request, the 401 Unauthorized HTTP response will be returned.
Authorization for the APIs is enforced at the endpoint level using permissions. Each secured endpoint has a predefined minimum level of permission that is required to be able to consume the endpoint. In order to access a particular endpoint, the user has to belong to a role that the above define permission level or higher level of permission is granted. If the authenticated user doesn’t satisfy the desired permission level, the 403 Forbidden HTTP response is sent back.
There are some open endpoints that do not require authentication and authorization based on particular use cases.
Errors
If an exception occurs while invoking a particular endpoint, you will receive an error response in the following format along with standard HTTP status codes.
New Self-service REST APIs for End-users
REST APIs for end-users who can be authenticated to the system to manage their user account-related activities.
- Manage challenge question answers
- View Authorized OAuth applications and revoke authorization from applications
- Manage associated accounts
- View and revoke login sessions
- Manage pending approvals
- Manage FIDO devices
- Manage TOTP registrations
Base path: /t/{tenant-domain}/api/user/{version}/me/
Sample request:
Samples and Trying It Out!
Details of the new APIs, with the Swagger UI, are included in our document space. You can try API endpoints using the Swagger UI sample requests. The documentation also provides details on how to run these in Postman. You can download the Swagger definition from the same page and generate a client or any Swagger-based tool to invoke the APIs. Furthermore, a respective postman collection can be found in our samples repository.