@open-age/express-api v2.8.1
Open Age Service
Overview
It is the framework component for openage services. It implements some of the boilerplate code like 1. User Authentication 2. Endpoint Authorization 3. Repsonse Standardization 4. Response Caching 5. Response Remapping 6. Bulk Request
It also builds the context and adds following mechanisms to it: 1. Caching 2. Configuration 3. Logging 4. Rules Evaluation
Release Notes
Version 2.7.9
Enhanced security:
- Implemented session validation with the authentication provider for a more robust authentication mechanism.
- Implemented session caching to save round trips (see session caching)
- Improved exception handling by hiding server errors and sending the one in
api.errors
section.
Refactorings
- Separated all the errors into it own error file
Version 2.6.0
- Implemented caching of the response.
Usage
Getting hierarchical configuration from the context
TODO:
- Complete documentation
Getting and Setting the Cache
TODO:
- Complete documentation
Setup
Installation
- Add the package
npm install @open-age/express-api --save
- Add dependencies
TODO:
- Complete documentation
Configuration
This component uses config package. The configuration can be defined at multiple levels. 1. Code Level 2. Installation Level 3. Organization Level 4. Tenant Level
Caching the response
Step 1: Configure cache server
You need to configure the application to use the cache configuration. Here is an example:
{
"cacheServer": {
"type":"redis",
"config": {
"host": "${env:cacheServer.host}",
"port": "${env:cacheServer.port}",
"options": {
"password": "${env:cacheServer.password}",
"maxmemory": "1gb",
"maxmemoryPolicy": "allkeys-lru"
}
}
}
}
Following cache servers are supported
This would also be used to cache the authentication data
Step 2: Configure the endpoint
You need to set the endpoint to cache the response. It can be defined at one of the following places (in the order of decreasing preference): 1. In the tenant configuration
{
"config": {
"api": {
"resource-get-by-id": {
"cache": {
}
}
}
}
}
- At service level
{
"api": {
"resource-get-by-id": {
"cache": {
}
}
}
}
- In the spec path file
specs/paths/:resource.js
.
{
"url": "/",
"get": {
"id": "resource-get-by-id",
"cache":{
}
}
}
The endpoint id, resource-get-by-id
is defined in spec/paths/resource.js
file. Even if the id the not defined it will be automatically created according to convention.
The cache section above would take following configuration
{
// unique id with which value will be saved
"key": "resource_${query}",
// seconds after which key and it's value will get deleted
"ttl": 2000,
// action to perfom when the endpoint is hit (defaults to add)
"action": "add",
// the condition(optional) that needs to be met
// for the response to be cache response
"condition": {
"operator": "AND",
"value": [{ "key": "query.field","operator": "==", "value": "value" }]
}
}
TODO:
- Add examples with more conditions
Securing an endpoint
Just like cache you need to configure the endpoint by adding permissions
to it
TODO:
- Complete documentation
Modifying a response
TODO:
- Complete documentation
Authentication
Validating the claims
Requesting ip with that of the token
{
"auth": {
"validate": {
"ip": true,
}
}
}
TODO:
- support for region in the ip like
in-*
Expiry of the token
- Following setting will check the expiry of the token against the current time
{
"auth": {
"validate": {
"expiry": true,
}
}
}
- Following setting will check the status of the session. It should not be
inactive
orexpired
{
"auth": {
"validate": {
"session": true,
}
}
}
Configuring how the service would authenticate the token
Using directory as auth provider
- Set the
auth.provider
asdirectory
{
"auth": {
"provider": "directory"
}
}
- Configure
providers.directory
. Note the system would fetch the session (from id) of the user under the credentials ofproviders.directory.role.key
{
"providers": {
"directory": {
"url": "http://api.openage.in/directory/v1/api", // prod url
"role": {
"key": "<role key of the tenant owner>"
}
}
}
}
Caching the session
Add sessions endpoints to the directory provider, and add the cache setting to it. You need to also add cacheServer setting
{
"providers": {
"directory": {
"endpoints": {
"sessions": {
"get": {
"cache": {
"ttl": 60000 // 60 seconds
}
}
}
}
}
}
}
If the cache is not defined, then the session won't be cahced
Using directory as auth provider
Sending out custom errors api.errors
{
"api": {
"errors": {
"UNKNOWN": {
"code": "UNKNOWN",
"message": "Internal Server Error"
},
"ACCESS_DENIED": {
"code": "ACCESS_DENIED",
"message": "Insufficient Permission"
}
}
}
}
4 months ago
4 months ago
4 months ago
4 months ago
5 months ago
6 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago
4 years ago
4 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
6 years ago
7 years ago