api-client-pkg

Usage

npm install @smg-automotive/api-client-pkg

Creating a client

Create a new typescript file and define an interface that describes your API. The interface must extend ClientConfiguration. The key defines the path to the API (use curly brackets for dynamic parameters) and the values define available methods for that path.

import {
  ApiClient,
  ClientConfiguration,
  RequestType,
  ResponseType,
} from '@smg-automotive/api-client-pkg';

interface ComparisonClientConfiguration extends ClientConfiguration {
  'users/me/listing-comparisons': {
    get: () => ResponseType<ListingComparison[]>;
    post: (
      request: RequestType<ListingComparison>
    ) => ResponseType<ListingComparisonCreateResponse>;
  };
  'users/me/listing-comparisons/{listingComparisonId}': {
    put: (request: RequestType<ListingComparison>) => ResponseType;
    delete: (request: RequestType) => ResponseType;
    get: (request: RequestType) => ResponseType<ListingComparison>;
  };
}

export const comparisonClient = ApiClient<ComparisonClientConfiguration>({
  baseUrl: 'https://api.automotive.ch/api',
  headers: {
    // your custom headers
  },
});

Each client needs to be configured by its own. The default values are:

property	type	default
baseUrl	string	""
headers	object	{ 'Content-Type': 'application/json' }

If you pass a custom configuration for a single API call with the RequestType object, the configuration is merged/overwritten.

await comparisonClient
  .path('users/me/listing-comparisons/{listingComparisonId}', {
    listingComparisonId: 1234,
  })
  .get({
    options: {
      baseUrl: 'https://someCustomBaseUrlForThatApi',
      headers: {
        // your custom headers
      },
      accessToken: 'your token',
    },
  });

Paginated requests

Backend APIs may implement standardized paginated endpoints. You can use the following helper types to type the request and response for an API providing paginated content.

interface VersionsClientConfiguration extends ClientConfiguration {
  'versions/search': {
    post: (
      request: RequestType<PaginatedQuery<VersionBody>, never>
    ) => ResponseType<never, PaginatedResponse<Version>>;
  };
}

Using the client

Depending on your client configuration, you are going to get typing for the request and the response body. The body is parsed and transformed to an object by the client.

const response = await comparisonClient
  .path('users/me/listing-comparisons/{listingComparisonId}', {
    listingComparisonId: 1234,
  })
  .get();

if (response.ok) {
  // response.body is typed to ListingComparison
} else {
  // something failed
}

If you are using curly brackets for the dynamic parameters, you also get typing for the path parameters. Furthermore, the api client replaces those occurrences automatically for you.

await comparisonClient
  // this will fail with "Property 'listingComparisonId' is missing"
  .path('users/me/listing-comparisons/{listingComparisonId}', {})
  .get();

await comparisonClient
  // this will call fetch with https://yourBaseUrl.ch/users/me/listing-comparisons/1234
  .path('users/me/listing-comparisons/{listingComparisonId}', {
    listingComparisonId: 1234,
  })
  .get();

Authorization

You can pass accessToken to the request options if you are talking to a protected API. The client will automatically set the header with a Bearer token.

// fetch is called with the header { Authorization: `Bearer ${accessToken}` }
await comparisonClient
  .path('users/me/listing-comparisons/{listingComparisonId}', {
    listingComparisonId: 1234,
  })
  .get({
    options: {
      accessToken: authHeader.accessToken,
    },
  });

Data sanitization

In case you need to sanitize data for a certain path or method you can pass sanitizers via the client configuration:

type Image = { s3Key: string };

type Listing = {
  images: Image[];
  make: string;
  model: string;
};

const sanitizeListing = ({ images, make, model }: Listing) => ({
  images: images || [],
  make: make || 'default make',
  model: model || 'default model',
});

interface ListingClientConfiguration extends ClientConfiguration {
  '/listings/{listingId}': {
    get: () => ResponseType<object, Listing>;
  };
}

export const listingClientWithSanitizers =
  ApiClient<ListingClientConfiguration>({
    baseUrl: 'https://api.automotive.ch/api',
    sanitizers: {
      '/listings/{listingId}': {
        get: sanitizeListing,
      },
    },
  });

This would apply the sanitizer for every get request on /listing/{listingId} path. It can be useful when you want to ensure some basic and sane defaults that cannot be guaranteed by the backend service.

Error handling

The promise is not rejected if any error occurs on API level ( see fetch documentation for reference). You can check for response.ok to know whether the request was successful or not and to get typing on the body object.

const response = await comparisonClient
  .path('users/me/listing-comparisons/{listingComparisonId}', {
    listingComparisonId: 1234,
  })
  .get({
    options: {
      accessToken: authHeader.accessToken,
    },
  });

if (response.ok) {
  // it worked!
} else {
  // it did not work for some reason
  if (response.status === 401) {
    // it did not work because user is not authorized!
  }
}

Testing

Create a file in the __mocks__ directory called @smg-automotive/api-client-pkg.ts with the following content:

export { ApiClient } from '@smg-automotive/api-client-pkg/dist/__mocks__/index';

By default, all the API calls will succeed and return an empty body. If you want to return a specific value you can do this by setting a spy on the created client:

import { comparisonClient } from '~/clients/userListingComparison';

jest.spyOn(comparisonClient, 'path').mockReturnValueOnce({
  get: jest.fn().mockReturnValueOnce(
    Promise.resolve({
      status: 401,
      body: { error: 'Unauthorized' },
      ok: false,
    })
  ),
});

if you want to overwrite the mock behavior of all used api-client functions in your test file, you can also use jest.mock for it:

jest.mock('@smg-automotive/api-client-pkg', () => ({
  ApiClient: () => ({
    path: () => {
      return {
        get: jest.fn().mockReturnValue(
          Promise.resolve({
            status: 401,
            body: { error: 'Unauthorized' },
            ok: false,
          })
        ),
        post: jest.fn(),
        put: jest.fn(),
        delete: jest.fn(),
      };
    },
  }),
}));

Development

npm run build

You can link your local npm package to integrate it with any local project:

cd smg-automotive-example-pkg
npm run build

cd <project directory>
npm link ../smg-automotive-example-pkg

Release a new version

New versions are released on the ci using semantic-release as soon as you merge into master. Please make sure your merge commit message adheres to the corresponding conventions.