Skip to content

Custom api data

Save new custom api

Basic Info

Here, you can specify custom API`s properties. 

1
2
3
4
5
6
7
8
9
name
label
requestMethod
path  
enableCaching 
resetCacheOnModificationOf
acceptOnlyEncryptedData
errorList
apiAccessType

  • While add/update custom API you can see the custom API settings code in the Basic Info tab.

Custom APIs default settings code 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import * as T from 'types';
import { EType } from 'types';

let customApi: T.ICustomApiSettingsTypes = {
    name: 'Hello World',
    label: 'Hello World',
    requestMethod: T.ERequestMethod.POST,
    path: '/hello-world',
    enableCaching: false,
    resetCacheOnModificationOf: [
        'DB:INSTANCE_NAME:DATABASE_NAME:COLLECTION_NAME',
        'CA:CUSTOM_API_NAME',
        'TP:BUNDLE_NAME:API_VERSION'
    ],
    acceptOnlyEncryptedData: false,
    errorList: ["Unable to process this request."],
    apiAccessType: T.EAPIAccessType.TOKEN_ACCESS,
    authTokenInfo: <T.IAuthTokenInfo[]>[
        {
            authTokenType: T.EAuthTokenType.AM_DB,
            authTokenAMDB: {
                "instance": "INSTANCE_NAME",
                "database": "DATABASE_NAME",
                "collection": "COLLECTION_NAME",
                "usernameColumn": "USER_NAME_COLUMN",
                "passwordColumn": "USER_PASSWORD_COLUMN"
            }
        }
    ]
};
module.exports = customApi;

Custom API Name

  • The name of the custom API should be unique.

Label

  • Custom APIs label is just a string that is shown everywhere.

Request method

  • Set request method for the custom API.
  • The request of that custom API should have given the method only.
  • Supported request methods are GET | POST | PUT | DELETE.

Path

  • A custom API path is used to call the custom API.
  • Add the path in the URL with the request method, and you will call that custom API.
  • The path must be unique.
  • The path and Request method combination must be unique.
1
2
Request URL: http://domain-name/api/custom-api/admin/hello-world
Request Method: POST

Enable caching

To enable caching of a particular custom API, set enableCaching: true. 

1
enableCaching: true | false

Reset cache on modification of

  • We can reset the cache of the custom API if any modification happens in the given collection/table, custom API, or third party API using resetCacheOnModificationOf.
  • DB: instance_name:database_name:collection|table, if modify/delete data of this collection/table system will automatically reset the cache of this [Hello World] custom API.
  • TP: api_bundle_name:api_version, if we hit any API of this version having [categoryRedis: EAPICategoryRedis.MODIFY_DATA], it will reset the cache of this [Hello World] custom API.
  • CA: custom_api_name, if we hit this custom_api, it will reset the cache of this [Hello World] custom API.

Accept only encrypted data

  • If you set the acceptOnlyEncryptedData value as true API Maker will accept only the encrypted body, query params, and URL.
  • In the header provide x-am-encrypted-payload: true when you set acceptOnlyEncryptedData: true.
1
acceptOnlyEncryptedData: true | false

Error list

  • API Maker users can set a custom error list for each custom API.
  • These errors will be listed in i18N, so you can map them in different languages.

In custom API settings 

1
errorList: ["Unable to process this request."]

Throw error in custom API code 

1
2
3
4
5
import * as T from 'types';
async function main(g: T.IAMGlobal) {
    throw new Error("Unable to process this request.");
}
module.exports = main;

API access type

  • There are two possible values of apiAccessType.
  • When you set IS_PUBLIC this collection's all APIs should be publicly available.
  • When you set TOKEN_ACCESS this collection's all APIs should require a token to access.
  • Provide API User token in the x-am-authorization header.
1
apiAccessType: IS_PUBLIC | TOKEN_ACCESS

Auth token info

  • If you do not provide authTokenInfo it will take authTokenInfo from the default secret.
1
// authTokenInfo: <T.IAuthTokenInfo[]>[]
  • If the authTokenInfo value is an empty array then provide only AM's API user's token in the x-am-authorization header because we are overriding the default secret's authTokenInfo. In that, you have to provide API Maker's API user token in the x-am-authorization header.
1
authTokenInfo: <T.IAuthTokenInfo[]>[]
  • Now, if you set authTokenType: T.EAuthTokenType.AM_DB and given required values in the authTokenAMDB object. The end user(who will use APIs) needs to provide the token in the x-am-user-authorization header.
  • The end user needs to create a token using the given instance, database, collection, usernameColumn, and passwordColumn values. Use the getToken system API to get the token.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
authTokenInfo: <T.IAuthTokenInfo[]>[
    {
        authTokenType: T.EAuthTokenType.AM_DB,
        authTokenAMDB: {
            "instance": "INSTANCE_NAME",
            "database": "DATABASE_NAME",
            "collection": "COLLECTION_NAME",
            "usernameColumn": "USER_NAME_COLUMN",
            "passwordColumn": "USER_PASSWORD_COLUMN"
        }
    }
]

Custom API Code

Here, you can call 

1
2
3
4
5
6
7
Generated apis 
Schema apis
External apis 
ThirdParty apis 
Events 
Systems apis
Utility classes

Basic code

  • Custom API has the async 'main' function. In which users will write their custom logic.
1
2
3
return {
    hello: 'world'
};

await, in custom API

  • Write 'await' before the global object 'g' to write asynchronous code.
  • Without 'await' it can be created problems.
1
2
3
4
5
return await g.sys.db.getAll({
    instance: "INSTANCE_NAME",
    collection: "COLLECTION_NAME",
    database: "DATABASE_NAME",
});

true, in custom API

  • Write 'true' that will help to non-stop execution of the custom API if that API gets an error response.
  • If the user does not write the 'true' it will stop the execution and throw the error.
  • One more use of 'true' is it will return whole response not only response data.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
let saveData = await g.sys.db.saveSingleOrMultiple({
    instance: "INSTANCE_NAME",
    collection: "COLLECTION_NAME",
    database: "DATABASE_NAME",
    saveData: {},
    headers: {}
}, true);
let countOfAllData = await g.sys.db.count({
    instance: "INSTANCE_NAME",
    collection: "COLLECTION_NAME",
    database: "DATABASE_NAME",
}, true);
return { saveData, countOfAllData };

Throw error from custom API

  • In custom API user can throw an error using the 'throw' keyword.
1
2
3
4
5
6
7
8
9
let saveData = await g.sys.db.saveSingleOrMultiple({
    instance: "INSTANCE_NAME",
    collection: "COLLECTION_NAME",
    database: "DATABASE_NAME",
    saveData: {},
    headers: {}
}, true);
if (saveData.success === false) throw 'Your data is not saved!';
else return saveData;

Get file custom API code

  • You can create a custom API that will download files for the application user.
1
2
g.res.contentType = 'image/gif';
return `data:image/gif;base64,R0lGODlhAQABAIAAAP///////yH5BAEKAAEALAAAAAABAAEAAAICTAEAOwA=`

Custom API Docs

Here, you can specify 

1
2
3
4
5
6
7
8
Business requirement 
Implementation logics
Pre requisite 
Validation 
Required documents 
Programming patterns
You may record timely
Many more ...