Class SHAFT.API

java.lang.Object
com.shaft.driver.SHAFT.API
Enclosing class:
SHAFT
public static class SHAFT.API extends Object
Manages a REST API session and exposes a fluent interface for building and executing HTTP requests (GET, POST, PUT, PATCH, DELETE).

Usage example: 

SHAFT.API api = new SHAFT.API("https://jsonplaceholder.typicode.com");
api.get("/posts/1").setTargetStatusCode(200);
api.assertThatResponse().extractedJsonValue("$.title").isNotNull();
See Also:

  • Constructor Details

    • API

      public API(String serviceURI)
      Creates a new API session pointing at the given base service URI.
      Parameters:
      serviceURI - the base URI of the target web service (e.g., "https://api.example.com")

    • API

      public API(String serviceURI, String storageStatePath)
      Creates a new API session pointing at the given base service URI, seeded with cookies read from a SHAFT browser storage-state JSON file (the same file produced by driver.browser().saveStorageState(String)).
      Parameters:
      serviceURI - the base URI of the target web service (e.g., "https://api.example.com")
      storageStatePath - path to a storage-state JSON file previously saved from a browser session

    • API

      public API(RestActions existingSession)
      Wraps an existing RestActions session for continued use.
      Parameters:
      existingSession - an already-initialised REST session

  • Method Details

    • getInstance

      public static SHAFT.API getInstance(String serviceURI)
      Factory method equivalent to new API(serviceURI).
      Parameters:
      serviceURI - the base URI of the target web service
      Returns:
      a new SHAFT.API instance

    • get

      public RequestBuilder get(String serviceName)
      Builds a GET request for the specified service endpoint.
      Parameters:
      serviceName - the endpoint path (appended to the base URI)
      Returns:
      a RequestBuilder for further request configuration

    • post

      public RequestBuilder post(String serviceName)
      Builds a POST request for the specified service endpoint.
      Parameters:
      serviceName - the endpoint path (appended to the base URI)
      Returns:
      a RequestBuilder for further request configuration

    • patch

      public RequestBuilder patch(String serviceName)
      Builds a PATCH request for the specified service endpoint.
      Parameters:
      serviceName - the endpoint path (appended to the base URI)
      Returns:
      a RequestBuilder for further request configuration

    • delete

      public RequestBuilder delete(String serviceName)
      Builds a DELETE request for the specified service endpoint.
      Parameters:
      serviceName - the endpoint path (appended to the base URI)
      Returns:
      a RequestBuilder for further request configuration

    • put

      public RequestBuilder put(String serviceName)
      Builds a PUT request for the specified service endpoint.
      Parameters:
      serviceName - the endpoint path (appended to the base URI)
      Returns:
      a RequestBuilder for further request configuration

    • head

      public RequestBuilder head(String serviceName)
      Builds a HEAD request for the specified service endpoint. HEAD returns the same headers/status as GET without a response body, so it is useful for existence, cache, and header assertions.
      Parameters:
      serviceName - the endpoint path (appended to the base URI)
      Returns:
      a RequestBuilder for further request configuration

    • options

      public RequestBuilder options(String serviceName)
      Builds an OPTIONS request for the specified service endpoint, typically used to inspect the allowed methods (CORS/preflight) an endpoint exposes.
      Parameters:
      serviceName - the endpoint path (appended to the base URI)
      Returns:
      a RequestBuilder for further request configuration

    • sendGraphQlRequest

      public RequestBuilder sendGraphQlRequest(String serviceName, String query)
      Builds a GraphQL POST request with a JSON body containing only the supplied query.
      Parameters:
      serviceName - the GraphQL endpoint path appended to the base URI
      query - the GraphQL query or mutation
      Returns:
      a RequestBuilder for further request configuration

    • sendGraphQlRequest

      public RequestBuilder sendGraphQlRequest(String serviceName, String query, Object variables)
      Builds a GraphQL POST request with query and variables.
      Parameters:
      serviceName - the GraphQL endpoint path appended to the base URI
      query - the GraphQL query or mutation
      variables - GraphQL variables, commonly a Map or JSON string
      Returns:
      a RequestBuilder for further request configuration

    • sendGraphQlRequest

      public RequestBuilder sendGraphQlRequest(String serviceName, String query, Object variables, String fragment)
      Builds a GraphQL POST request with query, variables, and fragment.
      Parameters:
      serviceName - the GraphQL endpoint path appended to the base URI
      query - the GraphQL query or mutation
      variables - GraphQL variables, commonly a Map or JSON string
      fragment - reusable GraphQL fragment content
      Returns:
      a RequestBuilder for further request configuration

    • addHeader

      public void addHeader(String key, String value)
      Adds a persistent header that will be sent with every subsequent request in this session.
      Parameters:
      key - the header name
      value - the header value

    • addCookie

      public void addCookie(String key, String value)
      Adds a persistent cookie that will be sent with every subsequent request in this session.
      Parameters:
      key - the cookie name
      value - the cookie value

    • importCookiesFrom

      public SHAFT.API importCookiesFrom(BrowserActionsContract browserActions)
      Imports all browser cookies into this API session.
      Parameters:
      browserActions - browser actions facade to read cookies from
      Returns:
      this API session for fluent chaining

    • importCookiesFrom

      public SHAFT.API importCookiesFrom(BrowserActionsContract browserActions, String domainFilter, String pathFilter)
      Imports browser cookies that match the optional domain and path filters into this API session.
      Parameters:
      browserActions - browser actions facade to read cookies from
      domainFilter - optional exact domain filter; pass null or blank to import every domain
      pathFilter - optional exact path filter; pass null or blank to import every path
      Returns:
      this API session for fluent chaining

    • exportCookiesTo

      public SHAFT.API exportCookiesTo(BrowserActionsContract browserActions)
      Exports all cookies from this API session into the given browser session.
      Parameters:
      browserActions - browser actions facade to write cookies into
      Returns:
      this API session for fluent chaining

    • exportCookiesTo

      public SHAFT.API exportCookiesTo(BrowserActionsContract browserActions, String domainFilter, String pathFilter)
      Exports API session cookies that match the optional domain and path filters into the given browser session.
      Parameters:
      browserActions - browser actions facade to write cookies into
      domainFilter - optional exact domain filter; pass null or blank to export every domain
      pathFilter - optional exact path filter; pass null or blank to export every path
      Returns:
      this API session for fluent chaining

    • getCookies

      public Map<String, io.restassured.http.Cookie> getCookies()
      Returns an immutable snapshot of cookies attached to this API session.
      Returns:
      API session cookies keyed by cookie name

    • getHeaders

      public Map<String,String> getHeaders()
      Returns an immutable snapshot of headers attached to this API session.
      Returns:
      API session headers keyed by header name

    • assertThatResponse

      public RestValidationsBuilder assertThatResponse()
      Starts building a hard assertion against the last API response.
      Returns:
      a RestValidationsBuilder for response assertions

    • verifyThatResponse

      public RestValidationsBuilder verifyThatResponse()
      Starts building a soft verification against the last API response.
      Returns:
      a RestValidationsBuilder for response verifications

    • getResponse

      public io.restassured.response.Response getResponse()
      Returns the raw REST Assured Response from the most recent request.
      Returns:
      the last Response

    • getResponseBody

      public String getResponseBody()
      Returns the response body of the most recent request as a string.
      Returns:
      the response body text

    • getResponseAs

      public <T> T getResponseAs(Class<T> responseType)
      Maps the most recent JSON response body to the requested Java type.
      Type Parameters:
      T - the mapped response type
      Parameters:
      responseType - the target class, record, or POJO type
      Returns:
      the response body mapped to responseType
      Throws:
      NullPointerException - if responseType is null
      IllegalStateException - if the response body is empty or the response is not JSON
      IllegalArgumentException - if the response body cannot be mapped to responseType

    • getResponseAsList

      public <T> List<T> getResponseAsList(Class<T> elementType)
      Maps the most recent JSON array response body to a list of the requested Java type.
      Type Parameters:
      T - the mapped list element type
      Parameters:
      elementType - the target class, record, or POJO type for each array item
      Returns:
      the response body mapped to a List
      Throws:
      NullPointerException - if elementType is null
      IllegalStateException - if the response body is empty or the response is not JSON
      IllegalArgumentException - if the response body cannot be mapped to List<elementType>

    • getResponseAs

      public <T> T getResponseAs(com.fasterxml.jackson.core.type.TypeReference<T> typeReference)
      Maps the most recent JSON response body to a generic Java type.
      Type Parameters:
      T - the mapped response type
      Parameters:
      typeReference - the target generic type reference
      Returns:
      the response body mapped to typeReference
      Throws:
      NullPointerException - if typeReference is null
      IllegalStateException - if the response body is empty or the response is not JSON
      IllegalArgumentException - if the response body cannot be mapped to typeReference

    • getResponseStatusCode

      public int getResponseStatusCode()
      Returns the HTTP status code of the most recent response.
      Returns:
      the status code (e.g., 200, 404)

    • getResponseTime

      public long getResponseTime()
      Returns the response time in milliseconds for the most recent request.
      Returns:
      the response time in milliseconds

    • getResponseJSONValue

      public String getResponseJSONValue(String jsonPath)
      Extracts a value from the most recent JSON response using a JSONPath expression.
      Parameters:
      jsonPath - the JSONPath expression (e.g., "$.data.id")
      Returns:
      the extracted value as a string

    • getResponseJSONValueAsList

      public List<Object> getResponseJSONValueAsList(String jsonPath)
      Extracts a list of values from the most recent JSON response using a JSONPath expression.
      Parameters:
      jsonPath - the JSONPath expression
      Returns:
      the extracted values as a list of objects

    • getResponseXMLValue

      public String getResponseXMLValue(String xmlPath)
      Extracts a value from the most recent XML response using an XPath expression.
      Parameters:
      xmlPath - the XPath expression
      Returns:
      the extracted value as a string

    • getResponseXMLValueAsList

      public List<Object> getResponseXMLValueAsList(String xmlPath)
      Extracts a list of values from the most recent XML response using an XPath expression.
      Parameters:
      xmlPath - the XPath expression
      Returns:
      the extracted values as a list of objects