DEV Community: unhurried

TypeScript REST API Client

unhurried — Fri, 22 May 2020 21:44:13 +0000

In this article, I will introduce a list of REST API client libraries I've researched which can be used in TypeScript (browser or Node.js).

Summary

axios and typed-rest-client have many users and stable development activities.
- As of Nov. 2019, axios is more popular than typed-rest-client. However, typed-rest-client might be going to get popularity in the future as it is maintained by Microsoft, that also maintains TypeScript.
Fetch API, which is a good option based on Web standard is not fully supported in all browsers, and some additional codes are required to support types.
- Using Polyfill would solve the browser support problem.
Generating client SDK with OpenAPI Generator will save a lot when OpenAPI (Swagger) spec is available.
- OpenAPI Generator is a project that was forked from Swagger Codegen and maintained by a community. It has more active development and more generators than Swagger Codegen. (cf. Swagger Codegen Fork: Q&A)
- Generators for TypeScript provided by OpenAPI Generator includes typescript-axios, typescript-fetch and typescript-anglar, that is made especially for Angular framework. (cf. Generators List)

Examples of Using Libraries

OpenAPI Generator

Generate a Client SDK

CLI tool can be install in various ways such as NPM or Docker image. (cf. CLI Installation)

Generators that don't depend on a specific framework are the ones using axios or Fetch API. As I mentioned earlier, I chose typescript-axios. You can generate a client SDK in your src directory with the following command.

openapi-generator generate -g typescript-axios -i ./openapi.yaml -o ./src/client-axios

Call an API with SDK

You can change the base URL when a URL specified in OpenAPI document is different from the actual one.

import { DefaultApi } from '@/client-axios';

const baseUrl = 'https://jsonplaceholder.typicode.com';
new DefaultApi({ basePath: baseUrl }).getToDo(1).then((res) => {
  console.log(res.data);
})

In case generated codes violate linter rules in your project, you need to configure the linter to ignore them.

# .eslintignore
src/client-axios

Also, when your project uses webpack and configures the type definition to use only webpack-env, you need to add a type definitions of Node.js modules because generated codes use url module in Node.js. (cf. TypeScript Configuration Reference)

// tsconfig.json
{
  "compilerOptions": {
    "types": ["webpack-env", "node"]
  }
}

axios

Define interface for response bodies and pass them as type parameters in axios API.

interface Todo {
  userId: number,
  id: number,
  title: string,
  completed: boolean,
}

import axios from 'axios';

const url = 'https://jsonplaceholder.typicode.com/todos/1';
axios.get<Todo>(url).then((res) => {
  console.log(res.data);
});

Reference

How to generate client libraries from OpenAPI
- https://blog.5thfloor.co.jp/2019/06/26/webapp-development-with-openapi-and-typescript/#openapi-generator-api-
- https://ky-yk-d.hatenablog.com/entry/2019/01/13/234108
Vue.js Cookbook
- It recommends axios as there still are some problems with Fetch API.

[TypeScript] Implement valueOf method in Enums

unhurried — Thu, 09 Jan 2020 11:43:30 +0000

Enums in Typescript don't have valueOf method, which returns an enum element from its string representation. This article explains how we can add valueOf method to Enums. Note that the implementation suggested in this article uses namespace as we cannot add arbitrary methods to Enums.

Numeric Enum

Numeric Enums, which assign incremental numbers to their elements, support reverse mapping . Therefore valueOf method can be implemented with Enum[string].

However we need to use one of the following expressions as Enum[string] produces a type error which says "Element implicitly has an 'any' type...".

Enum[string as keyof typeof Enum]
(<any>Enum)[string]

Implementation Example

/* Numeric Enum */
enum Color { Red, Green };

// toString()
Color.Green.toString(); // => '1'
Color[Color.Green]; // => 'Green'

// valueOf()
namespace Color {
  export function valueOf(str: string) {
    return Color[str as keyof typeof Color];
  }
}
const str = 'Green';
Color.valueOf(str); // => NumericEnum.Green

String Enum

String Enums, to which we can assign arbitrary string representations to their elements, don't support reverse mapping (*). Therefore we need to prepare a map object for reverse mapping by ourselves.

Implementation Example

/* String Enum */
enum Color { Red = 'red', Green = 'green' };

// toString()
Color.Green.toString(); // => 'green'

// valueOf()
namespace Color {
  const reverseMap = new Map<string, Color>();
  Object.keys(Color).forEach((s: string) => {
    const e = (<any>Color)[s];
    reverseMap.set(e.toString(), e);
  });
  export function valueOf(str: string) {
    return reverseMap.get(str);
  }
}
const str = 'green';
Color.valueOf(str); // => StringEnum.Green

* Enum elements can be retrieved by their key names just like numeric enums, but not by strings that are assigned to enum elements.

let str = 'Green'
Color[str as keyof typeof Color]; // => Color.Green
str = 'green'
Color[str as keyof typeof Color]; // => undefined

Reference

How to Change Key Bindings of vim-mode-plus

unhurried — Fri, 25 Oct 2019 10:36:55 +0000

vim-mode-plus, which is a plugin for Atom editor doesn't have a feature to load vimrc files that are common in Vim editor. Therefore, we need to prepare keymap.cson, which is the keymap configuration file of Atom and init.coffee, which is an initial configuration file of Atom, to assign multiple commands to one command.

I will introduce an example that converts a vimrc file to init.coffee and keymap.cson.

Before Conversion

vimrc

noremap j gj
noremap k gk

noremap <S-j> 10j
noremap <S-k> 10k
noremap <S-h> 10h
noremap <S-l> 10l

After Conversion

init.coffee

atom.commands.add 'atom-text-editor.vim-mode-plus', 'custom:move-left-10', ->
  view = atom.views.getView atom.workspace.getActiveTextEditor()
  atom.commands.dispatch view, 'vim-mode-plus:set-count-1'
  atom.commands.dispatch view, 'vim-mode-plus:set-count-0'
  atom.commands.dispatch view, 'vim-mode-plus:move-left'

atom.commands.add 'atom-text-editor.vim-mode-plus', 'custom:move-down-screen-10', ->
  view = atom.views.getView atom.workspace.getActiveTextEditor()
  atom.commands.dispatch view, 'vim-mode-plus:set-count-1'
  atom.commands.dispatch view, 'vim-mode-plus:set-count-0'
  atom.commands.dispatch view, 'vim-mode-plus:move-down-screen'

atom.commands.add 'atom-text-editor.vim-mode-plus', 'custom:move-up-screen-10', ->
  view = atom.views.getView atom.workspace.getActiveTextEditor()
  atom.commands.dispatch view, 'vim-mode-plus:set-count-1'
  atom.commands.dispatch view, 'vim-mode-plus:set-count-0'
  atom.commands.dispatch view, 'vim-mode-plus:move-up-screen'

atom.commands.add 'atom-text-editor.vim-mode-plus', 'custom:move-right-10', ->
  view = atom.views.getView atom.workspace.getActiveTextEditor()
  atom.commands.dispatch view, 'vim-mode-plus:set-count-1'
  atom.commands.dispatch view, 'vim-mode-plus:set-count-0'
  atom.commands.dispatch view, 'vim-mode-plus:move-right'

keymap.cson

'atom-text-editor.vim-mode-plus:not(.insert-mode)':
  'shift-h': 'custom:move-left-10'
  'shift-j': 'custom:move-down-screen-10'
  'shift-k': 'custom:move-up-screen-10'
  'shift-l': 'custom:move-right-10'
  'h': 'vim-mode-plus:move-left'
  'j': 'vim-mode-plus:move-down-screen'
  'k': 'vim-mode-plus:move-up-screen'
  'l': 'vim-mode-plus:move-right'

How to Set Up Vim Key Bindings in Atom

unhurried — Fri, 25 Oct 2019 10:31:31 +0000

I have been using Vim editor since I was a university student. However I start to think that Atom editor which has various plugins is more convenient in many cases.

To migrate from Vim to Atom smoothly, I've researched how to configure Vim key bindings in Atom.

Install Plugins

vim-mode-plus and ex-mode are recommended.

Note: vim-mode and vim-mode-plus-ex-mode are deprecated.

Turn off IME when exit the insert mode with Esc

We need to use several 3rd party applications to change the key bindings because Atom plugins can not turn off IME.

Karabiner (for MacOS) or AutoHotKey (for Windows) seem to be popular. (However, these applications cannot reset IME when we enter the insert mode again.)

Configure key bindings for plugins

You need to define key bindings in keymap.cson as vim-mode-plus doesn't have a feature to load vimrc files.
If you need to issue multiple commands in a key binding, you need to register a custom command in init.coffee.

Convert Markdown into HTML with Sphinx

unhurried — Fri, 04 Oct 2019 09:42:05 +0000

Little notes of a study on a method to convert a markdown file into a HTML file with Sphinx. You can find the deliverable of this study in sphinx-with-markdown.

Enable markdown syntax in Sphinx

Install recommonmark and register it as a markdown parser.

pip install recommonmark

conf.py

source_suffix = ['.rst', '.md']
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
}

Activate AutoStructify component that enables the eval_rs syntax to embed reStructuredText in markdown and syntax highlighting by adding the following configuration in conf.py.

from recommonmark.transform import AutoStructify
def setup(app):
    app.add_config_value('recommonmark_config', {
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)

Install sphinx_markdown_tables as recommonmark by itself doesn't support markdown table syntax.

pip install sphinx-markdown-tables

conf.py

extensions = [
    'sphinx_markdown_tables',
]

Internationalization (Multilingualization)

Sphinx has an internationalization feature (sphinx-intl) on top of gettext.

Installation

pip install sphinx-intl

Usage

# Compile messages to translate from source code in pot files in {build dir}/gettext.
make gettext
# Generate po files from pot files in {source dir}/locale.
sphinx-intl update -p build/gettext -l en

# Edit the generated po files.

# Specify a language and generate translated documents. 
make -e SPHINXOPTS="-D language='en'" html

When you update the document, you can update po files in the same way.

Edit a PO file

PoEdit is a easy-to-use editor though its complementary version has several feature limitations.

Reference

https://conyac.cc/ja/business/columns/localization_guide_po_pot

HTML Themes

Various HTML themes can be found in sphinx-themes.org.

Read the Docs theme seems to be popular among sphinx users.

Docker Image

There are several images in DockerHub which set up sphinx, but none of them seems to be maintained well. Therefore I chose to build my own image from python official image (alpine).

hnakamur/sphinx
- The version of installed sphinx is still 2.0.1 (latest version is 2.1.2.).
docker-sphinx-rtd-theme
- You can use the latest sphinx as its version is not specified in Dockerfile.
- Python is a little old (3.6), and sphinx-intl is not installed.
plaindocs/docker-sphinx
- Pushed once 4 years ago. Its image size is relatively large as it is based on Ubuntu.

Known Issues

The markdown list syntax * item is converted into <li><p>item</p></li>, resulting in generating additional p element and causing styling problems in some HTML templates.
Inline styles will be deleted when converting into po files, and they need to be added manually in reST syntax.

Tips

Avoid Warnings on toctree

Sphinx generates a warning when it finds a document which is not included in any toctree.

checking consistency... C:\Users\xxx\Desktop\sx\source\test.md: WARNING: document isn't included in any toctree

To suppress the warning, add orphan in the first line of the document.

Other Useful Packages

Export documents in ePub format: pip install Pillow
Watch changes on documents and re-build automatically: pip install sphinx-autobuild

Reference

Deploying a Web API on AWS Lambda: Difference between API Gateway and Application Load Balancer

unhurried — Sat, 07 Sep 2019 23:25:43 +0000

When we deploy a web API on AWS Lambda leveraging the benefit of server less architecture, we have two options for the front-end service for Lambda: API Gateway (API GW) or Application Load Balancer (ALB). This articles studies the difference between them to help you to decide which to choose.

Features unique to API Gateway

It is obvious, but API Gateway specific features such as Request Validation, Data Mapping, Access Control and SDK Generation cannot be used with ALB.

Protocols and Port Numbers

API GW supports only HTTPS (TLS 1.2) on 443 port. Note that though API GW supports VPC Endpoint, you still need to use HTTPS in this case too.
ALB supports both HTTP and HTTPS on arbitrary port numbers and TLS version also can be chosen from various options.

Request Timeout

API GW has a severe limitation of 29 seconds.
ALB itself doesn't have a limitation, thus the timeout of Lambda (up to 15 minutes) is applied.

Request and Response Sizes

API GW can handle up to 6MB payload, which is the ceiling of Lambda's payload size.
- Note that 6MB includes headers and Base64-encoded body as payloads are requests and responses of Lambda.
- The limitation of API GW's payload size is 10MB.
With ALB, the size of request and response bodies cannot be larger than 1MB. 413 error will be returned when a request body exceeds the limit, and 502 error for response body.

Request Event（Reference）

evt.headers (Request)
- API GW sets header names and values with keeping the original upper and lower cases, whereas ALB decapitalize header names.
evt.queryStringParameters (Request)
- When there is no query string parameter, API GW sets null, whereas ALB sets {}.
- API Gateway sets the URL decoded value for query string parameter key and value, whereas ALB sets them without URL decoding.
evt.multiValueHeaders / evt.multiValueQueryStringParameters (Request)
- API Gateway sets these parameters by default, whereas ALB requires that they are enabled in its configuration.

Response Event（Reference）

ALB response event must include statusDescription, isBaseEncoded and headers (when "Multi Value Header" is enabled in ALB configuration).

Cost

Up to a certain request frequency, API GW is cheaper than ALB, that has a time-based charge. However for the services that receive a large amount of requests, ALB is more reasonable. (Reference)

Other References

Amazon Web Services Blog
- It only mentions as follows:there’s also a lot of overlap and commonality between the parameters used by Amazon API Gateway for triggering Lambda functions and ALB’s parameters.
API Gateway vs Application Load Balancer—Technical Details
API Gateway vs. ALB - 持田システム
- It covers the difference in request timeout and limitation on response size.

A Token Management Implementation for Web API Authentication in Java

unhurried — Mon, 19 Aug 2019 21:54:20 +0000

This article studies an implementation of a synchronized process in Java that enables multiple threads to share same timed tokens, assuming access tokens in OAuth2, for Web API authentication.

Specification of Token Management

I assume the following specification for this token management system.

Multiple threads call Web APIs with the same token.
When a token expires, a thread that detects the expiration first will update the token.
During the update process, token retrievals from other threads needs to wait the completion of the update.

An Implementation in Java

The following is an implementation of the token management system described above.

public class TokenManager {

  // Singleton Pattern
  private static TokenManager instance = new TokenManager();
  private TokenManager() {}
  public static TokenManager getInstance() {
    return instance;
  }

  /* Set "volatile" to variables for token and update time so that any
     threads can retrieve the up-to-date state of the variables. */
  // Timed token
  private volatile String token = null;
  // Update time calcurated from TTL of the token
  private volatile long refreshAt = 0L;

  // getToken doesn't need "synchronized" as any threads can retrieve
  //  the up-to-date token with the aid of "volatile" keyword.
  public String getToken() {
    if (System.currentTimeMillis() >= refreshAt) {
      syncUpdateToken();
    }
    return this.token;
  }

  // Make the method "synchronized" so that only one thread can
  // execute it in time.
  private synchronized void syncUpdateToken() {
    // Prevent subsequents threads that call getToken method during
    // the token update from updating the token again.
    if (System.currentTimeMillis() < refreshAt) {
      return;
    }

    // Token Update Process
    // Update "token" before "refreshAt" as "refreshAt" is used
    // first in getToken method to check the token expiration.
    this.token = ...
    this.refreshAt = ...
  }
}

By making instance variables (token and refreshAt) "volatile", getToken method doesn't need "synchronized", which enables parallel execution of token retrievals while the token is valid.

Note that results in subsequent threads invoking updateToken method, thus token expiration check is also needed in updateToken to prevent unnecessary token updates.