CSF.Screenplay.WebApis Extension

The Web APIs Extension allows Actors to communicate with HTTP web API endpoints within a Screenplay Performance.

Overview

The fundamentals of this Screenplay extension are shown in the diagram below. The concepts of the Actor and Ability (the ability is named MakeWebApiRequests) are explained in Screenplay's core documentation. Other concepts are explained below.

This extension provides Actions which allow the Actor to build and send HTTP requests based upon Endpoint definitions. These requests are sent via the HTTP client which is exposed by the MakeWebApiRequests Ability, to a live API server. The server returns an HTTP Response, which the extension formats into a result object.

flowchart 
  Ability -- "Has ability" --> Actor
  Actor -- "Makes requests" --> Request
  Endpoint -- "Requests target" --> Request
  Request --> api["Live API"]
  Ability -- "Facilitates request" --> api
  api --> Response

  style api fill:#ee9,stroke:#bb6

Note that the Live API in this diagram is not a part of Screenplay or this extension. The Live API represents an actual HTTP(S) web server which hosts the API with which Screenplay is communicating.

Usage example

Here is a brief usage example for using a JSON API with a defined endpoint, identified by URL and HTTP method. The endpoint expects a parameter of a PersonId (a fictitious class, which accepts a person's name as a constructor parameter). The endpoint returns a JSON-formatted response which is a representation of an Animal (another fictitious class, which has a string Name property).

using static CSF.Screenplay.WebApis.WebApiBuilder;

static readonly JsonEndpoint<PersonId,Animal> getFavouriteAnimal = new ("https://api.example.com/person/getFavouriteAnimal", HttpMethod.Post);

// this method would appear as part of a custom-written Task class,
// deriving from IPerformableWithResult<string>
public async ValueTask<string> PerformAsAsync(ICanPerform actor, CancellationToken cancellationToken)
{
    var animal = await actor.PerformAsync(GetTheJsonResult(getFavouriteAnimal, new("Jane Doe")), cancellationToken);
    return animal.Name;
}