Multi-tenancy in REST API
Multi-tenancy architecture helps us to share the resources cost-efficiently and securely in cloud environments where the single instance of the software runs on a server and serves multiple tenants. In which statelessness plays a major role in scaling for millions of concurrent users. Statelessness means that every Http request(API) happens in complete isolation. When the client makes an Http request, it includes all the information necessary for the server to fulfill that request.
In this article, I will be sharing different ways to build REST API for multi-tenant stateless application which will be consumed by different client application such as Mobile, Web browser and Integration platforms, etc.
When it comes to multi-tenancy the only variant is the tenant Id. Since its a stateless system, the system needs to know tenant information in order to process the request and get the corresponding resources. For example, each tenant’s data either get saved in different tenant database or separated with tenant id as a namespace. The only option for the backend to access the tenant-specific is to send the tenant identifier part of every API.
URL: <scheme>://<domain>/<path>?<query-param>#<nose>
A URL contains scheme/protocol and a domain. Every URL get differentiated from others by changing the path or query param. I have listed some of the methods in which a tenant can get identified as part of REST API,
Query parameter based tenant identification
In this approach, the client will send the tenant-id as part of the parameter to the server in addition to other required parameters they need to send. This is not a recommended approach to implement multitenant based API’s.
example:
https://<your-domain>.com/<api-context>?tenantid=<tenant-id>&<other-parameters>
URL path based tenant identification
In this approach, the API is designed in a way to mandatorily accommodate tenant-id as part of the URL path. So that the server can parse the URL path to get the tenant-id. Most of the multitenant system uses this approach to identify their tenant context.
example:
https://<your-domain>.com/<tenant-id>/<api-context>
Domain-based tenant identification
In this method, your application is accessed by your client via their own subdomain. This approach the server requires an additional effort to maintain the mapping between the tenant’s domain and tenant id from your end.
example:
https://<tenant-domain>.<your-domain>.com/<api-context>
<tenant-domain>:<tenant-id>
Custom Http header-based tenant identification
In this method, we can pass the tenant-id as part of your own custom Http headers like X-TENANT-ID. It's not recommended to use custom headers as a way of addressing multitenancy or a resource. They should be used instead to pass ancillary information like accept types, auth tokens, etc.
As part of the custom attribute in JWT token
JSON Web Token is an open industry standard for representing claims securely between two parties. Click here to know more about JWT.
The JWT token’s payload will have two information logged-in user’s identification and its corresponding tenant identification. This token will be sent part of a client cookie or a custom header.
example:
{
“sub”: “1234567890”,
“name”: “<user-name>”,
“iat”: 1516239022,
“userid”: “<user-id>”,
“tenantid”: “<tenant-id>”
}
We have seen different ways on how a tenant id can be represented in REST API. When it comes to which is best or which one to choose? its just a question of taste, choose the one that suits you most. The one we’ve used in our API implementation is by having the tenant-id part of the URL path. I would suggest the URL path and sub-domain based tenant identification when compared to other options.
