restapi-typescript-decorators
Inspired by retrofit (created by Square), my goal for this project is to create a single rest client for both front end JS as well as back end node JS using just decorators (also known as annotations in the Java's world). These decorators are used to make REST API calls simpler and more declarative
Another inspiration is to create a unified Rest Client library that works across the stack. In this case, to support node js and frontend code in a single code base. The goal is to create a single decorator for both node js and frontend.
Features
TODO's
How to use?
You can also checkout the sample repos that has typescript and other things setup:
Live Demo
You can test a live demo of the frontend code at https://synle.github.io/restapi-typescript-decorators-front-end-example/dist/
Install it
install from npm
npm i --save restapi-typescript-decorators@^6
Make sure you have the typescript and decorator enabled in your tsconfig.json
Simple Code Example
Most of these examples return ApiResponse<any>
for simplicity. You can use the library to cast the response object in a custom format. Refer to the bottom section of this guide for how to do type cast your requests and responses.
import the classes
import {
ApiResponse,
CredentialProperty,
FileUploadBody,
FormDataBody,
PathParam,
QueryParamProperty,
QueryParams,
RequestProperty,
RequestBody,
RestApi,
RestClient,
} from 'restapi-typescript-decorators';
Public (non authenticated) API Store
Below is an example on the definition for public API data store.
import {
RestClient,
RestApi,
RequestProperty,
RequestBody,
PathParam,
QueryParamProperty,
QueryParams,
FormDataBody,
FileUploadBody,
ApiResponse,
} from 'restapi-typescript-decorators';
export interface HttpBinRequest {
[propName: string]: any;
}
export interface HttpBinResponse {
args?: {
[propName: string]: any;
};
headers?: {
[propName: string]: any;
};
origin?: string;
url?: string;
data?: {
[propName: string]: any;
};
json?:
| string
| {
[propName: string]: any;
};
form?: {
[propName: string]: any;
};
[propName: string]: any;
}
@RestClient({
baseUrl: 'https://httpbin.org',
})
export class PublicApiDataStore {
@RestApi('https://httpbin.org/get')
doGetWithAbsoluteUrl(): ApiResponse<HttpBinResponse> {}
@RestApi('/get')
doGetWithQueryParams(@QueryParams _queryParams: HttpBinRequest): ApiResponse<HttpBinResponse> {}
@RestApi('/get')
doGetWithSingleQueryParam(
@QueryParamProperty('keyword') _keyword: string = '',
@QueryParamProperty('pageSize') _pageSize: number = 100,
): ApiResponse<HttpBinResponse> {}
@RestApi('/get')
doGetWithQueryParamsCombo(
@QueryParams _query: HttpBinRequest,
@QueryParamProperty('pageSize') _pageSize: number = 100,
): ApiResponse<HttpBinResponse> {}
@RestApi('/anything/{recordId}')
doGetWithPathParams(@PathParam('recordId') _recordId: string): ApiResponse<HttpBinResponse> {}
@RestApi('/anything/{messageId}')
doGetWithPathParamsAndQueryParams(
@PathParam('messageId') _messageId: string,
@QueryParams _queryParams: HttpBinRequest,
): ApiResponse<HttpBinResponse> {}
@RestApi('/delay/10', {
timeout: 3000,
})
doGetWithTimeout(): ApiResponse<HttpBinResponse> {}
@RestApi('/status/405')
doErroneousAPI(): ApiResponse<HttpBinResponse> {}
@RestApi('/{encodingToUse}')
doGetWithResponseEncoding(
@PathParam('encodingToUse') _encoding: 'brotli' | 'gzip' | 'deflate',
): ApiResponse<HttpBinResponse> {}
@RestApi('/xml', {
headers: {
Accept: 'application/xml',
},
})
doGetWithXmlResponse(): ApiResponse<HttpBinResponse> {}
@RestApi('/robots.txt', {
headers: {
Accept: 'text/plain',
},
})
doGetWithPlainTextResponse(): ApiResponse<string> {}
@RestApi('/post', {
method: 'POST',
})
doPostWithJsonBodyHash(@RequestBody _body: HttpBinRequest): ApiResponse<HttpBinResponse> {}
@RestApi('/post', {
method: 'POST',
})
doPostWithSingleValuesJsonBody(
@RequestProperty('firstName') _firstName: string,
@RequestProperty('lastName') _lastName: string,
): ApiResponse<HttpBinResponse> {}
@RestApi('/post', {
method: 'POST',
})
doPostWithJsonBodyMixture(
@RequestBody _body: HttpBinRequest,
@RequestProperty('userId') _userId: string,
): ApiResponse<HttpBinResponse> {}
@RestApi('/post', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
})
doPostWithEncodedFormData(@RequestBody _body: HttpBinRequest): ApiResponse<HttpBinResponse> {}
@RestApi('/anything', {
method: 'POST',
})
doPostWithFormBodyData(
@FormDataBody('unitPrice') _unitPrice: number,
@FormDataBody('quantity') _qty: number,
): ApiResponse<HttpBinResponse> {}
@RestApi('/anything', {
method: 'POST',
})
doUploadFileWithFormBodyData(
@FormDataBody('mySms') _mySmsContent: HttpBinRequest,
): ApiResponse<HttpBinResponse> {}
@RestApi('/post', {
method: 'POST',
})
doUploadFileWithStreamRequest(@FileUploadBody _fileToUpload: any): ApiResponse<HttpBinResponse> {}
}
Then instantiate it as
import { PublicApiDataStore } from './PublicApiDataStore';
const myApiInstance = new PublicApiDataStore();
Use it
You can use the response in a few ways.
Option 1 (preferred): with if
check
const apiResponse = myApiInstance.doGetWithQueryParams({a: 1, b: 2});
if(apiResponse){
apiResponse.result.then(
resp => {
// do something with your response
}
);
}
Option 2: no if check with await and async
async function doWorkFunc(){
const apiResponse = myApiInstance.doGetWithQueryParams({a: 1, b: 2});
if(apiResponse){
try{
const resp = await apiResponse.result;
// do something with your response
} catch(e){
// api error, do some handler
}
}
}
Private (authenticated with Bearer Token) API Store
Below is an example on the definition for private API data store.
import {
RestClient,
RestApi,
CredentialProperty,
ApiResponse,
} from 'restapi-typescript-decorators';
export interface HttpBinAuthResponse {
authenticated: boolean;
user?: string;
token?: string;
[propName: string]: any;
}
@RestClient({
baseUrl: 'https://httpbin.org',
authType: 'Bearer',
})
export class PrivateBearerAuthApiDataStore {
@CredentialProperty('AccessToken')
accessToken: string;
constructor(newAccessToken: string = '') {
this.accessToken = newAccessToken;
}
@RestApi('/bearer', {
method: 'GET',
})
doAuthenticatedCall(): ApiResponse<HttpBinAuthResponse> {}
}
Then instantiate it as
import { PrivateBearerAuthApiDataStore } from './PrivateBearerAuthApiDataStore';
const myApiInstance = new PrivateBearerAuthApiDataStore('good_username', 'good_password');
Private (authenticated with username and password basic auth) API Store
import {
RestClient,
RestApi,
CredentialProperty,
ApiResponse,
} from 'restapi-typescript-decorators';
export interface HttpBinAuthResponse {
authenticated: boolean;
user?: string;
token?: string;
[propName: string]: any;
}
@RestClient({
baseUrl: 'https://httpbin.org',
authType: 'Basic',
})
export class PrivateBasicAuthApiDataStore {
@CredentialProperty('Username')
username: string;
@CredentialProperty('Password')
password: string;
constructor(newUsername: string = '', newPassword: string = '') {
this.username = newUsername;
this.password = newPassword;
}
@RestApi('/basic-auth/good_username/good_password', {
method: 'GET',
})
doAuthenticatedCall(): ApiResponse<HttpBinAuthResponse> {}
}
Then instantiate it as
import { PrivateBasicAuthApiDataStore } from './PrivateBasicAuthApiDataStore';
const myApiInstance = new PrivateBasicAuthApiDataStore('good_username', 'good_password');
To execute the RestClient
const myApiInstance = new PrivateApiDataStore('<<some_strong_and_random_access_token>>');
const apiResponse = myApiInstance.doApiCallWithBearerToken();
if(apiResponse){
apiResponse.result.then((resp) => {
// ... do something with your response and status code ...
console.log('ok', apiResponse.ok);
console.log("url", apiResponse.url);
console.log('status', apiResponse.status);
console.log('resp', resp);
});
}
To abort pending Rest calls
Sometimes you want to abort a pending Rest call. You can use apiResponse.abort()
. Note that this action will also disable any attempt to retry the API for any pending instance method invokation. Say you are calling a fetch user with 5 retries, if you do abort
. At that moment in time, the API will stop the pending API call and any retry.
const apiResponse = myApiInstance.doApiCallWithBearerToken();
if (apiResponse) {
apiResponse.result.then((resp) => {
});
apiResponse.abort();
}
Simple GET REST Calls with Query String
You can use either @QueryParams
(as a hash) or @QueryParamProperty
(as a single value for query string). This will send a GET request to the backend with query string attached. The library will handle url encoding for your data. So no need to encode it when using this API.
This example will pass a hash (queryStringKey => queryStringValue) into the query string
@RestApi('/get')
doGetWithQueryParams(@QueryParams _queryParams: HttpBinRequest): ApiResponse<HttpBinResponse> {}
This example will pass a single value into the query string
@RestApi('/get')
doGetWithSingleQueryParam(
@QueryParam('keyword') _keyword: string = '',
@QueryParam('pageSize') _pageSize: number = 100,
): ApiResponse<HttpBinResponse> {}
Notes on mixture of @QueryParams
and @QueryParamProperty
When both @QueryParamProperty
and @QueryParams
are present in a single method, final result for query string will be merged with single value @QueryParamProperty
has higher precedence than @QueryParams
hash.
Below is an example of this:
@RestApi('/get')
doGetWithQueryParamsCombo(
@QueryParams _query: HttpBinRequest,
@QueryParamProperty('pageSize') _pageSize: number = 100,
): ApiResponse<HttpBinResponse> {}
Simple GET REST Calls with Path Param
@PathParams can be used in a class members (class attributes) or method parameters.
Below is an example of how path params can be used in a class member
@RestApi("/anything/{messageId}")
doGetWithPathParams(
@PathParam("messageId") _targetMessageId: string
): ApiResponse<any> {}
The following code shows how path params can be used in class members and method parameters
@RestClient({
baseUrl: 'https://httpbin.org/cookies/set/{cookieName}/{cookieValue}',
})
export class PathParamApiDataStore {
@PathParam('cookieName')
cookieName: string;
constructor(newCookieName: string = '') {
this.cookieName = newCookieName;
}
@RestApi()
doGet(@PathParam('cookieValue') _newCookieValue: string): ApiResponse<HttpBinResponse> {}
}
Simple GET REST Calls with Path Param and Query String
@RestApi('/anything/{messageId}')
doGetWithPathParamsAndQueryParams(
@PathParam('messageId') _targetMessageId: string,
@QueryParams _queryParams: HttpBinRequest,
): ApiResponse<HttpBinResponse> {}
Simple POST Rest Calls with JSON Body
You can post JSON body with @RequestBody
(as a hash) or @RequestProperty
(as a single value).
Below is an example of how to POST JSON with @RequestBody
(as a hash)
@RestApi('/post', {
method: 'POST',
})
doPostWithJsonBody(@RequestBody _body: HttpBinRequest): ApiResponse<HttpBinResponse> {}
Below is an example of how to POST JSON with @RequestProperty
(as a single value).
@RestApi('/user_profile', {
method: 'POST',
})
updateUserProfile(
@RequestProperty('firstName') _firstName: string,
@RequestProperty('lastName') _lastName: string,
): ApiResponse<HttpBinResponse> {}
Notes on mixture of @RequestBody
and @RequestProperty
When both @RequestProperty
and @RequestBody
are present in a single method, final result for query string will be merged with single value @RequestProperty
has higher precedence than @RequestBody
hash.
Below is an example of this:
@RestApi('/post', {
method: 'POST',
})
doPostWithJsonBodyMixture(
@RequestBody _body: HttpBinRequest,
@RequestProperty('userId') _userId: string,
): ApiResponse<HttpBinResponse> {}
Simple POST Rest Calls with FormData Body
@RestApi('/anything', {
method: 'POST',
})
doPostWithFormBodyData(
@FormDataBody('unitPrice') _unitPrice: number,
@FormDataBody('quantity') _qty: number,
): ApiResponse<HttpBinResponse> {}
Simple POST Rest Calls with File Upload as Stream
This example uploads the file as a single stream
@RestApi('/post', {
method: 'POST',
headers: {
'Content-Type': 'multipart/form-data',
},
})
doSimpleUploadFileWithStreamHttpBinPost(
@FileUploadBody _fileToUpload: any,
): ApiResponse<HttpBinResponse> {}
This expects your response to be a buffer. Below is how you can craft the buffer for Node Js
import fs from 'fs';
const sampleSmsFileStream = fs.createReadStream('SampleSms.txt');
const apiResponse =
myPublicDataStoreInstance.doSimpleUploadFileWithStreamHttpBinPost(sampleSmsFileStream);
URL Notes
By default, the library will construct the url to use as:
- When
@RestApi.url
is a relative url (for example "/myAPI
"). The url by appended the url
from @RestApi
to baseUrl
from @RestClient
as:
urlToUse = @RestClient.baseUrl + @RestApi.url
- When
@RestApi.url
is an absolute url which starts with http://
or https://
(for example "https://httpbin.org/get
" or "http://httpbin.org/get
"). That absolute url will be used and won't be appended to the baseUrl
urlToUse = @RestApi.url
Type casting your response type
Sometimes it might be useful to cast / parsing the json object in the response to match certain object type. We can do so with this library using this approach.
Then RestClient class will look something like this
import {
RestClient,
RestApi,
CredentialProperty,
RequestBody,
PathParam,
FileUploadBody,
QueryParams,
FormDataBody,
ApiResponse,
} from 'restapi-typescript-decorators';
interface NumberPair {
a: number;
b: number;
}
interface CollectionSum {
sum: number;
}
@RestClient({
baseUrl: 'https://httpbin.org',
})
export class TypeCastApiDataStore {
@RestApi('/calculateSum', {
method: 'POST',
})
doPostWithTypeCasting(@RequestBody requestBody: NumberPair): ApiResponse<CollectionSum> {}
}
Max timeout for API
You can set a max timeout using the timeout
attribute. In which the API will be aborted if the timeout has passed.
In this example, the actual API will return in 10 seconds, but the client will timeout and abort the request in 3 seconds
@RestApi('/delay/10', {
timeout: 3000,
})
doSimpleTimeoutAPI(): ApiResponse<HttpBinResponse> {}
API Retries
For cases when API can fail due to some QPS (Query Per Second) requirements and the vendor wants the user to attempt a retry at a later time, you can set the parameter for retryConfigs which allows the API to be retried. This way the API will be called again until the totalRetry has passed. To use this, simply set the retryConfigs
under the @RestApi
decorator.
This example below will retry if there's failure in the response. It will wait a second before attempting a new retry.
As for checking how many retries has been attempted to reach the API. You can refer to the retryCount
property of the ApiResponse
.
Note:
- That when the user attempted to abort the API calls manually using the
abort()
method from ApiResponse
, this action will stop the API from further retries. - Another note is that the client will respect server
Retry-After
response header. And will attempt to retry after that delay. At the moment we only support Retry-After
that is of number of seconds to invoke an API retry
@RestClient({
baseUrl: 'http://localhost:8080',
})
export class RetryDataStore {
@RestApi('/hello', {
retryConfigs: {
count: 5,
delay: 1000,
},
})
doApiWithRetry(): ApiResponse<HttpBinResponse> {}
}
Understanding the ApiResponse.result Promise
It's the promise that wrapped around the fetch calls. At the moment, the API will return the resolved promise state when the API is successful, and rejected state if the call is aborted by the user or it's an API network error.
Request and Response Format
By default, the library will help parsing of the response when you set the proper value for Accept
Header.
To use the default parser, you can set the Accept Header. This example below will tell the library to parse the response as if the response is a XML. The default behavior is to parse response as JSON.
Parse JSON Request
The default header value for Content-Type
is application/json
. You can also be explicit about it. But basically it will transform your JSON request object into JSON string understood by the backend that consumes JSON.
@RestApi('/post', {
method: 'POST',
})
doSimpleHttpBinPostJsonBody(@RequestBody _body: HttpBinRequest): ApiResponse<HttpBinResponse> {}
Parse URL Encoded Form Request
The default header value for Content-Type
is application/x-www-form-urlencoded
. When this is provided, the library will send your request in url encoded form format.
@RestApi('/post', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
})
doSimpleHttpBinPostEncodedForm(
@RequestBody _body: HttpBinRequest,
): ApiResponse<HttpBinResponse> {}
Parse Response as XML
This will parse the XML response and return them as JSON object
@RestApi('/xml', {
})
doSimpleHttpGetWithXmlData(): ApiResponse<HttpBinResponse> {}
Parse Response as JSON
The default header value for Accept
is application/json
. You can also be explicit about it. But basically it will transform your response into JSON objects.
@RestApi('/json', {
headers: {
'Accept': 'application/json',
},
})
doSimpleJSONGet(): ApiResponse<HttpBinResponse> {}
You can also provide fast-xml-parser
custom configurations for the client using @RestClient
property xmlParseOptions
at the class level.
@RestClient({
baseUrl: 'https://httpbin.org',
xmlParseOptions: {
attrPrefix: '@_',
textNodeName: '#text',
ignoreNonTextNodeAttr: true,
ignoreTextNodeAttr: true,
ignoreNameSpace: true,
},
})
export class TransformationApiDataStore {
@RestApi('/xml', {
method: 'POST',
headers: {
Accept: 'application/xml',
},
})
doSimpleRequestTransformApi(@RequestBody requestBody: NumberPair): ApiResponse<any> {}
}
Transformations
You can use requestTransform
and responseTransform
to do transformation on the request and response API. You can define the transformation at both the @RestClient
or @RestApi
level. When both are defined, a more specific tranformation at @RestApi
will be used toward the final transformation.
Simple request transform
This example will transform the request before sending the request to the backend. The example will do some translation to the input data before sending the data to the backend.
import {
RestClient,
RestApi,
CredentialProperty,
RequestBody,
PathParam,
FileUploadBody,
QueryParams,
FormDataBody,
ApiResponse,
} from 'restapi-typescript-decorators';
interface NumberPair {
a: number;
b: number;
}
@RestClient({
baseUrl: 'https://httpbin.org',
})
export class TransformationApiDataStore {
@RestApi('/anything', {
method: 'POST',
requestTransform: (
fetchOptions: Request,
pair: NumberPair,
instance: TransformationApiDataStore,
): Promise<Request> => {
const newBody = {
a: pair.a * 100,
b: pair.b * 200,
};
return Promise.resolve(
Object.assign(fetchOptions, {
body: JSON.stringify(newBody),
}),
);
},
})
doPostWithRequestTransformation(@RequestBody requestBody: NumberPair): ApiResponse<any> {}
}
const myTransformationApiDataStoreInstance = new TransformationApiDataStore();
const apiResponse = myTransformationApiDataStoreInstance.doPostWithRequestTransformation({
a: 1,
b: 2,
});
if (apiResponse) {
}
Simple response transform
This example will transform the response before returning the final result to the front end. The example code will add the response values and return the sum as the response
import {
RestClient,
RestApi,
CredentialProperty,
RequestBody,
PathParam,
FileUploadBody,
QueryParams,
FormDataBody,
ApiResponse,
} from 'restapi-typescript-decorators';
interface NumberPair {
a: number;
b: number;
}
@RestClient({
baseUrl: 'https://httpbin.org',
})
export class TransformationApiDataStore {
@RestApi('/anything', {
method: 'POST',
responseTransform: (
fetchOptions: Request,
resp: Response,
instance: TransformationApiDataStore,
): Promise<any> => {
return resp.json().then((respJson) => {
const pair = <NumberPair>JSON.parse(respJson.data);
const sum = pair.a + pair.b;
return Promise.resolve({ sum });
});
},
})
doPostWithResponseTransformation(@RequestBody requestBody: NumberPair): ApiResponse<any> {}
}
const myTransformationApiDataStoreInstance = new TransformationApiDataStore();
const apiResponse = myTransformationApiDataStoreInstance.doPostWithResponseTransformation({
a: 300,
b: 700,
});
if (apiResponse) {
}
Config Overrides
We have 3 layers of configs: DefaultConfig
(default configs from this library), @RestClient
Custom Configs and @RestApi
Custom Configs. The final config values are set using this order DefaultConfig
, @RestClient
, and @RestApi
.
Config Override Table
DefaultConfigs | @RestClient | @RestApi | Config To Use |
---|
a | b | c | c |
a | b | | b |
a | | c | c |
| b | c | c |
a | | | a |
| b | | b |
| | c | c |
Config Override Example
Below is an example on how to set Custom Config
import {
RestClient,
RestApi,
CredentialProperty,
RequestBody,
PathParam,
FileUploadBody,
QueryParams,
FormDataBody,
ApiResponse,
} from 'restapi-typescript-decorators';
import { HttpBinResponse } from './types';
@RestClient({
baseUrl: 'https://httpbin.org',
headers: {
'Accept-Encoding': 'ASCII',
'--Rest-Client-Custom-Header': '<some_value_@Restclient_111>',
'--Rest-Api-Custom-Header': '<this_value_will_overrided>',
},
})
export class OverrideConfigApiDataStore {
@RestApi('/anything', {
method: 'POST',
mode: 'no-cors',
cache: 'reload',
credentials: 'same-origin',
headers: {
'Accept-Encoding': 'UTF8',
'Content-Type': '<some_value_@RestApi_333>',
'--Rest-Api-Custom-Header': '<some_value_@RestApi_222>',
},
})
doPostWithCustomRestApiConfig(): ApiResponse<HttpBinResponse> {}
}
With the above example
--Rest-Api-Custom-Header
: will be <some_value_@RestApi_222>
because it's set in @RestApi which has more specificity even though its value in @RestClient
is <this_value_will_overrided>
--Rest-Client-Custom-Header
: will be <some_value_@Restclient_111>
because it's set inside of @RestApi
although it's not defined anywhere else in DefaultConfigs
or @RestClient
Content-Type
: will be application/json
because it's set in the DefaultConfigs
even though we didn't specify it.
Notes
- For POST method and POST JSON body of
appplication/json
, the request will stringify and properly saves it into the body - Note that when both
@RequestBody
and @FormDataBody
are used, @FormDataBody
will have higher precendence
How to contribute?
Make the change and create PR against master.
Issues?
If you have any issue with the API, feel free to file a bug on Github at https://github.com/synle/restapi-typescript-decorators/issues/new
Note on release pipeline
To publish directly to npm
Beta Tags
npm run build && \
npm version prepatch && \
npm publish --tag beta
Prod Tags
npm run build && \
npm version patch && \
git push origin master