Class EndpointBase
- Namespace
- CSF.Screenplay.WebApis
- Assembly
- CSF.Screenplay.WebApis.dll
Abstract base class for types which represent web API endpoints.
public abstract class EndpointBase : IHasName- Inheritance
-
EndpointBase
- Implements
- Derived
-
Endpoint<TResult>ParameterizedEndpoint<TParameters>ParameterizedEndpoint<TParameters, TResponse>
- Inherited Members
Remarks
An endpoint is broadly a description of a Web API URL and the corresponding HTTP method (aka "verb") such as GET or POST. Instances of endpoints (types which derive from this base class) are typically stored as static readonly values in Screenplay-based logic. Here, they can be reused by tasks or other performables.
Choose an appropriate implementation of this type based upon your intended use case. Endpoints which expect the API to return a strongly-typed result within the response body include a generic type parameter for the type of that result object. Also, endpoints which expect a request body: "parameterized endpoints" include a generic type parameter for the type of that request payload. There are also specialisations of these parameterized endpoint classes for those which expect an object serialized to JSON as their request payload.
When writing custom endpoints, do not derive directly from this type. Usually one of the following pre-written endpoint types will be suitable for your use case. If not, pick the one which most closely matches your use-case and derive from that.
- Endpoint
- Endpoint<TResult>
- ParameterizedEndpoint<TParameters>
- ParameterizedEndpoint<TParameters, TResponse>
- JsonEndpoint<TParameters>
- JsonEndpoint<TParameters, TResult>
For more information, see the documentation article for using web APIs.
Constructors
EndpointBase(string, HttpMethod)
Initializes a new instance of a type which derives from EndpointBase with a relative URI and an optional HTTP method.
protected EndpointBase(string relativeUri, HttpMethod method = null)Parameters
relativeUristringA relative URI string for the current endpoint.
methodHttpMethodAn optional HTTP method.
Remarks
When setting the relative URI, avoid a leading forward-slash. Prefer myApp/doSomething over /myApp/doSomething.
If you omit the HTTP method, then the created builder will also not specify an HTTP method, which
(if used to generate a request) will result in an HTTP GET request. See CreateRequestMessage().
EndpointBase(Uri, HttpMethod)
Initializes a new instance of a type which derives from EndpointBase with a URI and an optional HTTP method.
protected EndpointBase(Uri uri, HttpMethod method = null)Parameters
uriUriA URI for the current endpoint; this may be relative or absolute.
methodHttpMethodAn optional HTTP method.
Remarks
If you omit the HTTP method, then the created builder will also not specify an HTTP method, which
(if used to generate a request) will result in an HTTP GET request. See CreateRequestMessage().
Properties
Name
Gets the human-readable name of the current object.
public virtual string Name { get; init; }Property Value
Examples
For an endpoint implementation which represents a GET request to a user profile API, this property could be overridden so that it includes the user ID of the user which is requested.
Remarks
null is strongly discouraged here. All types which implement IHasName should return a non-null response from this property.
Where it comes to endpoints, it is normal that the human-readable name might be influenced by state which is held within the specific endpoint implementation. In these cases, developers are encouraged to override this property, providing a name which includes the relevant values.
Timeout
Gets or sets an optional timeout duration for requests built from this endpoint.
public TimeSpan? Timeout { get; init; }Property Value
Remarks
If this set to a non-null value, then the HTTP client used to make the request will include cancellation after an amount of time (equal to this timespan) has passed. This logic is handled within the MakeWebApiRequests action. If this action is not used then this timeout might not be honoured.
The logic for honouring this timeout is contained within the performables which are shipped with this library:
- SendTheHttpRequest
- SendTheHttpRequestAndGetTheResponse<TResponse>
- SendTheHttpRequestAndGetJsonResponse<TResponse>
If different performables are used to interact with the current endpoint then they must implement any timeout-related logic themselves, or else this value will not be honoured.
Methods
GetBaseHttpRequestMessageBuilder()
Gets a HttpRequestMessageBuilder from the state of the current instance.
protected HttpRequestMessageBuilder GetBaseHttpRequestMessageBuilder()Returns
- HttpRequestMessageBuilder
An HTTP request message builder
Remarks
Derived types should make use of this method to get the request message builder from the state of this base class. They may then further-customize the message builder according to their own logic. The message builder returned from this method will respect the following state from the endpoint.
GetBaseHttpRequestMessageBuilder<TResponse>()
Gets a HttpRequestMessageBuilder<TResponse> from the state of the current instance, with information about the expected response type.
protected HttpRequestMessageBuilder<TResponse> GetBaseHttpRequestMessageBuilder<TResponse>()Returns
- HttpRequestMessageBuilder<TResponse>
An HTTP request message builder
Type Parameters
TResponse
Remarks
Derived types which expect a strongly-typed response from the API should make use of this method to get the request message builder from the state of this base class. They may then further-customize the message builder according to their own logic. The message builder returned from this method will respect the following state from the endpoint.