Non-Polynomial Mantissa

    ts-retrofit2
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.2 • Public • Published

    ts-retrofit 2

    Declarative and type-safe HTTP client for Node.js and Web

    build status github package npm package npm downloads license

    Test coverage

    Statements Branches Functions Lines
    Statements Branches Functions Lines

    Installing

    Using npm:

    $ npm install ts-retrofit2

    Using yarn:

    $ yarn add ts-retrofit2

    Introduction

    Automatically turn your decorated methods into axios HTTP requests.

    export class GitHubService extends BaseService {
      @GET("/users/{user}/repos")
      listRepos(@Path("user") user: string): ApiResponse<Repo[]> {}
    }

    Build a service:

    const service = new ServiceBuilder()
      .baseUrl("https://api.github.com/")
      .build(GitHubService);
    
    const repose = await service.listRepos("octocat");

    Use decorators to describe the HTTP request.

    Inlined response body

    If you need only response body you can inline it

    export class GitHubService extends BaseService {
      @GET("/users/{user}/repos")
      listReposWithInlinedBody(@Path("user") user: string): ApiResponseBody<Repo[]> {}
    }
    const service = new ServiceBuilder()
      .baseUrl("https://api.github.com/")
      .inlineResponseBody()
      .build(GitHubService);
    
    const repose = await service.listRepos("octocat");

    API Declaration

    Decorators on the methods and its parameters indicate how a request will be handled.

    REQUEST METHOD

    Every method must have an HTTP decorator that provides the request method and relative URL. There are built-in decorators: GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD. The relative URL of the resource is specified in the decorator param.

    @GET("users/list")

    You can also specify query parameters in the URL.

    @GET("users/list?sort=desc")

    URL MANIPULATION

    A request URL can be updated dynamically using replacement blocks and parameters on the method. A replacement block is an alphanumeric string surrounded by { and }. A corresponding parameter must be decorated with @Path using the same string.

    @GET("group/{id}/users")
    groupList(@Path("id") groupId: string): ApiResponse<User[]> {}

    Query parameters can also be added using @Query.

    @GET("group/{id}/users")
    groupList(@Path("id") groupId: string, @Query("sort") sort: string): ApiResponse<User[]> {}

    For complex query parameter can be added using @QueryMap. It should be object with primitive properties.

    @GET("group/{id}/users")
    groupList(@Path("id") groupId: string, @QueryMap query: SearchQuery): ApiResponse<User[]> {}

    REQUEST BODY

    @POST("users/new")
    groupList(@Body user: User): ApiResponse<User> {}

    FORM ENCODED AND MULTIPART

    @POST("/user/edit")
    @FormUrlEncoded
    formUrlEncoded(
      @Field("first_name") first: string,
      @Field("last_name") last: string,
    ): ApiResponse<User> {}

    Multipart requests are used when @Multipart is present on the method. Parts are declared using the @Part decorator.

    @PUT("user/photo")
    @Multipart
    updateUser(
      @Part("description") description: PartDescriptor<string>,
      @Part("photo") file: PartDescriptor<Buffer>,
    ): ApiResponse<User> {}

    HEADER MANIPULATION

    You can set static headers for a method using the @Headers decorator.

    @GET("widget/list")
    @Headers({
      "Cache-Control": "max-age=640000",
    })
    widgetList(): ApiResponse<Widget> {}
    @GET("users/{username}")
    @Headers({
      "Accept": "application/vnd.github.v3.full+json",
      "User-Agent": "Retrofit-Sample-App"
    })
    getUser(@Path("username") username: string): ApiResponse<Widget> {}

    A request Header can be updated dynamically using the @Header decorator. A corresponding parameter must be provided to the @Header. If the value is null, the header will be omitted. Otherwise, toString will be called on the value, and the result used.

    @GET("user")
    getUser(@Header("Authorization") authorization: string): ApiResponse<User> {}

    Similar to query parameters, for complex header combinations, a @HeaderMap can be used.

    @GET("user")
    getUser(@HeaderMap headers: MyHeaders): ApiResponse<User> {}

    Headers that need to be added to every request can be specified using an interceptor.

    Install

    npm i ts-retrofit2

    DownloadsWeekly Downloads

    29

    Version

    2.2.2

    License

    MIT

    Unpacked Size

    8.28 kB

    Total Files

    3

    Last publish

    Collaborators

    • npwork