import {CallAnApi} from '@serenity-js/rest/lib/screenplay/abilities'
public class | source

CallAnApi

An Ability that enables the Actor to call a HTTP API. If you need to connect via a proxy, check out this article.

Implements:

Examples:

Using a default Axios HTTP client
 import { Actor } from '@serenity-js/core';
 import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
 import { Ensure, equals } from '@serenity-js/assertions';

 const actor = Actor.named('Apisit').whoCan(
     CallAnApi.at('https://myapp.com/api'),
 );

 actor.attemptsTo(
     Send.a(GetRequest.to('/users/2')),
     Ensure.that(LastResponse.status(), equals(200)),
 );
Using Axios client with custom configuration
 import { Actor } from '@serenity-js/core';
 import { CallAnApi, GetRequest, LastResponse, Send } from '@serenity-js/rest'
 import { Ensure, equals } from '@serenity-js/assertions';

 import axios from 'axios';

 const axiosInstance = axios.create({
     timeout: 5 * 1000,
     headers: {
         'X-Custom-Api-Key': 'secret-key',
     },
 });

 const actor = Actor.named('Apisit').whoCan(
     CallAnApi.using(axiosInstance),
 );

 actor.attemptsTo(
     Send.a(GetRequest.to('/users/2')),
     Ensure.that(LastResponse.status(), equals(200)),
 );

Tests:

Static Method Summary

Static Public Methods
public static

Used to access the Actor's ability to CallAnApi from within the Interaction classes, such as Send.

public static

at(baseURL: string): CallAnApi

Ability to Call and api at a specified baseUrl

public static

using(axiosInstance: AxiosInstance): CallAnApi

Ability to Call a REST API using a given axios instance.

Constructor Summary

Public Constructor
public

constructor(axiosInstance: AxiosInstance)

Method Summary

Public Methods
public

mapLastResponse(fn: function<T>(AxiosResponse): T): T

Maps the last cached response to another type.

public

modifyConfig(fn: function(original: AxiosRequestConfig): any): void

Allows for the original Axios config to be changed after the CallAnApi Ability has been instantiated and given to the Actor.

public

Sends a HTTP request to a specified url.

public

resolveUrl(config: AxiosRequestConfig): string

Resolves the final URL, based on the AxiosRequestConfig provided any any defaults AxiosInstance has been configured with.

Static Public Methods

public static as(actor: UsesAbilities): CallAnApi source

Used to access the Actor's ability to CallAnApi from within the Interaction classes, such as Send.

Params:

NameTypeAttributeDescription
actor UsesAbilities

Returns:

CallAnApi

public static at(baseURL: string): CallAnApi source

Ability to Call and api at a specified baseUrl

Default timeout is set to 2s.

Default request headers:

  • Accept: application/json,application/xml

Params:

NameTypeAttributeDescription
baseURL string

Returns:

CallAnApi

public static using(axiosInstance: AxiosInstance): CallAnApi source

Ability to Call a REST API using a given axios instance.

Useful when you need to customise Axios to make it aware of proxies, for example.

Params:

NameTypeAttributeDescription
axiosInstance AxiosInstance

Returns:

CallAnApi

Public Constructors

public constructor(axiosInstance: AxiosInstance) source

Params:

NameTypeAttributeDescription
axiosInstance AxiosInstance

A pre-configured instance of the Axios HTTP client

Public Methods

public mapLastResponse(fn: function<T>(AxiosResponse): T): T source

Maps the last cached response to another type. Useful when you need to extract a portion of the AxiosResponse object.

Params:

NameTypeAttributeDescription
fn function<T>(AxiosResponse): T

mapper function

Returns:

T

public modifyConfig(fn: function(original: AxiosRequestConfig): any): void source

Allows for the original Axios config to be changed after the CallAnApi Ability has been instantiated and given to the Actor.

Params:

NameTypeAttributeDescription
fn function(original: AxiosRequestConfig): any

Returns:

void

public resolveUrl(config: AxiosRequestConfig): string source

Resolves the final URL, based on the AxiosRequestConfig provided any any defaults AxiosInstance has been configured with.

Params:

NameTypeAttributeDescription
config AxiosRequestConfig

Returns:

string