11 Oct, 2019 | 3 min read

REST APIs - What and Why?

  • Ayesha Dissanayaka
  • Associate Director/Architect - 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.


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


  • 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:

  1. Basic authentication: Use the user’s credentials in the API invocation
  2. OAuth 2 common flows: Obtain a token using an oauth2 flow and use the token when invoking the API
  3. 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.


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.

All the possible errors that can occur while invoking these APIs are listed in this error catalogue.

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.

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.


The latest version of WSO2 Identity Server provides REST APIs for self-service, and you will see a range of REST APIs supported in our future releases. With this, developers can easily integrate self-service functions to third-party applications. To learn more about the capabilities and range of APIs supported by WSO2 Identity Server, read the Kuppingercole Leadership compass on Identity API platforms, where we were named an overall leader. If you’re yet to try WSO2 Identity Server, you can do that here.