Introducing REST-Assured

REST-Assured is a tool that will will be useful for our component tests when sending incoming requests to our Schedule service. This is a DSL that uses the Given When Then semantics and makes clear readable tests.

REST-Assured allows us to construct requests and to closely control the payloads that are sent to the controller. It is possible to pass specific headers and query params to the URL. REST-Assured then allows us to inspect the result and interrogate exactly what the response is. This includes the HTTP Status code, headers and response body.

REST-Assured has a variety of language implementations so should not just be seen as a Java tool. There are other implementations that employ a similar style for testing.

Security component test example

In our example, the components that are being tested are the incoming requests to our Schedules service. When a client makes a request to the endpoint “/schedules” it is important that it is routed to the correct Controller that will perform the business logic upon this request. There are further criteria that should be validated when requests are made such as to ensure that when making calls to our services that no information is leaked if a consumer probes our service. Validation that our service is not leaking any of this information is really important and where component testing is useful. Another key area to validate is security. In our Schedule service there is a security requirement that all authorized clients can make a request to see the schedules, however, only specific authorized end users are able to create a new schedule. Again a selection of units are grouped together to ensure that when a request is made to our service that it will allow an authorized user access to see the schedules.

For our Schedule service a controller has been created that will take requests from an authenticated user

  @GetMapping
  public Mono<ValueEntity<ConferenceSession>> getSchedules(
      @AuthenticationPrincipal JwtAuthenticationToken principal) {
    if (!READ_SCHEDULE_CLAIM
        .equals(principal.getToken().getClaimAsString("scope"))) {
      return Mono.error(
            new AccessDeniedException("Not required Authorization")
        );
    }
    return sessionService.getAllSessions()
      .flatMap(sessionDecorator::decorateSession)
      .collectList()
      .map(conferenceSchedules -> new ValueEntity(conferenceSchedules));
  }

This controller was written using TDD, however, the Authenticated Principal passed in was created in the unit test. This is why it is important to verify the security of this controller and the Spring Security framework is working with our component. Component tests will verify the controller fulfilled the following criteria:

• Requests will not reach the controller if no Authenticated principal is provided

• Requests that have an incorrect scope will return a status of 403

• Requests that are successful have response of 200

Here we show the second test case in the list above. Please refer to the github for the other test cases

@Test
void return_a_forbidden_response_with_missing_read_scope_supplied() {
  given()
    .webTestClient(
      webTestClient.mutateWith(
        mockJwt().jwt(jwt -> jwt.claim("scope", "schedules:WRITE"))
      )
    )
    .when()
      .get("/schedules")
    .then()
      .status(HttpStatus.FORBIDDEN);
}

What can be seen here is that the tests assert the expected behavior that was laid out. This essential testing gives us confidence that the endpoint is secure and will not leak data to unauthorized parties.

Component testing shows us the value of the units working together and can confirm whether the units work together as expected.

External Service integration

A common requirement for a project is to integrate with another service or module.

The validation that should be performed is to confirm that when communicating across the boundary that the interaction is correct with this external service. For this external service integration the case that will be examined is the Schedule service communicating with the Sessions service.

How do we know that an external service integration is validated

• Ensuring that an interaction is being made correctly e.g. for a RESTful service this may be specifying the correct URL or the payload body is correct

• Is the data being sent in the correct format?

• Can the unit that is interacting with external service handle the responses that will be returned?

Ideally, we would have a list of interactions with an external service and be able to validate these without having to speak to the actual service itself. If the Schedule service speaks to the actual Sessions service then this would be part of End to End testing which is later on in “UI Testing”. So, how can we validate that the two services can talk to each other?

Options for testing with an external service

The first and most obvious solution is to use what was learned in “Introduction to REST” and to look at an API specification that a Sessions service produces. By looking at the API specification it is possible to see all the endpoints and the requests and responses that are available to us. This also means that if an API first approach is taken to a system (“Specifying REST APIs”) an OpenAPI spec will be available for use.

Introduction to stubbing with Wiremock

Another option is to create a stub server of the Sessions service API that can be run locally as part of a test. It is possible to use a tool such as Wiremock to facilitate this stubbing.

By using WireMock it is possible to construct a stub server directly in code in tests or to create mappings files which are JSON files that describe an API interaction. WireMock can be ran as a standalone process so this does not limit you to a programming language or enforce only running it for testing. It is possible to run a stub server and use it in an environment as a replacement for a real service. An example case and mappings file is shown towards the end of “Why use API Contracts”.

The process of using WireMock is to standup the stub server for your tests to represent an external service. The WireMock server is then fed interactions that it should respond to. So when representing the Schedules service a mapping will be fed to it that effectively states, when a request is made to this endpoint (e.g. “/schedules”), then respond with this body. If no matches are made an error is returned.

However, there is an issue here that immediately causes concern. The concern is actually writing the stub code. As the developers wish to have a stubed external service they need to create it by hand with their understanding of how the Schedule service should work. What if interaction is incorrectly defined, such as the expected response is written incorrectly?

There is a solution to this if the API service is already available. WireMock again can be used to capture real requests and responses by proxying the requests through it. More information on how to do this is available in the WireMock documentation These captured requests and responses are saved as mapping files and then can be used to use WireMock for testing or as a stub service for numerous cases such as a dev test environment when actual requests to an API may cost actual money.

By capturing the API requests with another service the concerns of writing mappings by hand are averted as they are instead being generated. This does not solve the issue when a new API interaction is being defined or the API interaction is extended and again the solution is to write the new API interaction or extend the stub server.

Stubbing is a common practice and something that the Authors have used in the past as it works and provides value. As long as the team is aware of the limitations these are fair techniques to use and provides invaluable testing across the external boundary.

There is another technique to use for testing with external services, though first let’s walk through a typical scenario for a new project that many readers will be familiar with or looking to undertake: A new project is created and two teams want or need to integrate their products together. They decide on the core interactions that they need and write a document with a list of endpoints for the new RESTful service. Payloads are defined of what is sent and what will be received. After time passes the two teams deploy the first iteration and they find that some or all of the interactions are not working.

Classic examples of why interactions are not working include:

• The URLs do not match the document as someone has decided on new and “better” convention

• The client of the service has mistyped a property name

• The response is expected as an object but gets returned as an array of objects as this will make it “future proof”

An API first approach has been tried in this example, all parties try to do the right thing and make the best product. However, there is nothing to hold the services to account on the agreement made in the document. The producer of the API needs to uphold what they will respond with and the consumer needs to validate it is calling the API correctly.

For a real life situation what is being described for this document is at best handshake agreement of what each party will do. What is desired is something like a that looks more like a contract!

There is good news that API Contracts do exist.

API Contracts

AAs a consumer of an API it has always been a good idea to test with a Test Stub service (like the WireMock services just described and as a producer of an API there is huge value in being able to know how your service is going to be called.

API Contracts are a written definition of an interaction between two entities a Consumer and a Producer. A Producer responds to the API requests, it is producing data. e.g. a RESTful Web Service A Consumer requests data from an API. e.g. web client, terminal shell

Producers are also known as Providers. In this book the word Producer will be used, though the reader should be aware that they are interchangeable and provider is the term of choice in some contract frameworks.

When looking at the C4 model of the the interactions of our Schedule service it is valuable to see the UI is calling the service through the API Management solution and that the service is requesting data from both the Attendee and Sessions service.

Figure 3-6. Producer and Consumer elements of schedule service highlighted

Therefore we can say that the Schedule service is a Producer for the API Management Application and it is a Consumer of the Sessions service and Attendee service.

Why use API Contracts

The beauty of defining an interaction with a contract is that it is possible to generate tests and stubs from this. Automated tests and stub services are what give us the ability to perform local testing without reaching out to the actual service, though still allow us to verify an interaction.

To understand of how tests can be auto generated and stub servers can be created it is important to see an API contract. For our example as the Schedule service is being written in Java the Contract framework that will be used is Spring Cloud Contracts. However, the section “API Contract Frameworks” discusses other API Contract frameworks.

The Schedule service is communicating with the Sessions Service and it was decided as part of the build that the Sessions service would use API Contracts. We can see from the image the three contracts. These contracts are the Get sessions as a GET, a Create Session as a POST and a Remove Session as a DELETE.

Figure 3-7. Contracts of sessions service

The piece of functionality that the sessions service is lacking is the ability to modify a session. This is a candidate for submitting a contract for this new interaction with the Sessions service.

Here is the contract for the new interaction. It shows how the Producer shall respond and how the Consumer should interact with the new PUT endpoint.

import org.springframework.cloud.contract.spec.Contract

Contract.make {
  // (1) Request entity
  request {
    // (2) Description of what the contract does
    description("""Modify a Schedule Resource""")
    // (3) The HTTP Method that the consumer will call
    method PUT()
    // (4) The URL endpoint that will be hit
    urlPath '/sessions/session-id-1'
    // (5) The Headers that should be passed by the callee
    headers {
      // (6) Header of ContentType with value 'application/json'
      contentType('application/json')
    }
    // (7) The Body of the request
    body(
        // (8) A name property
        name: "An Introduction to Contracts",
        // (9) A description property
        description: "A beginners guide to Contracts",
        // (10) A speaker id array property
        speakerIds: [
          // (11) An array of speaker ids
          "bryant-1",  "auburn-1"
        ]
    )
  }
  // (12) Response entity
  response {
    // (13) The status from producer should be NO CONTENT, 204
    status NO_CONTENT()
  }
}

This should hopefully look familiar as it has the look and feel of a generic Request and Response that you see in HTTP interactions. This is a real benefit as it makes writing and reading contracts simple for people not familiar with Groovy.

Let us go through this contract step by step and explain what is happening.

The first part, the most outer definition, is merely stating that we are defining a contract:

Contract.make{

}

The two entities are the request and the response so let us first check the request we have defined in the contract. In this request it is shown what the Consumer should send to the Producer. The response is next and shows what the Producer should respond with

As we look at the contract as a whole what is being said is, When a PUT request is sent to /sessions/session-id-1 which has a header with Content-Type that is equal to application/json and the body of the request has a name property that matches “An Introduction to Contracts” and a description that equals “A beginners guide to Contracts” a Response with the status 204 is returned.

We now have a full definition of a contract and to reiterate this is a definition of an interaction and NOT behavior. The contract is stating that the Producer has to return a 204 status code (when successful), it does not care how the producer does this in the background. If this were a legal contract and you are told to pay a fine, the court does not care how you procure the money (hopefully legally) so long as you pay the fine issued. This is a defined interaction, the court will get the money, and for an API the consumer will get the defined response.

One thing you may have noticed is hardcoded values such as the id of session-id-1 enforced by the contract. This works fine as from the definition we can easily tell what the contract is intended todo, however, we can make the contract more generic by using regular expressions for defined properties. Here we see the same contract in a more generic manor.

  // (12) Response entity
  response {
    // (13) The status from producer should be NO CONTENT, 204
    status NO_CONTENT()
  }

As can be seen in the annotated code the values can be generated or inferred by the testing framework. For a Consumer, When a PUT request is sent to /sessions/{ID} which has a header with Content-Type that is equal to application/json and the body of the request has a name property that is a non blank string and a description that is a non blank string a Response with the status 204 is returned. For a Producer, When a PUT request is sent to /sessions/session-id-1 which has a header with Content-Type that is equal to application/json and the body of the request has a name property that is a non blank string and a description that is a non blank string a Response with the status 204 is returned It is not suggested that all contracts be as generic as possible, hardcoded values are not bad, however, generic values can be useful for the generated contract tests.

As this contract is something that the producer (Schedule service) should fulfill it is possible to generate tests from this contract. This is logical as, this is an interaction that is entirely defined. The generated test from this contract is the following:

@SuppressWarnings("rawtypes")
public class ContractVerifierTest extends BaseContract {

  @Test
  public void validate_modify_session() throws Exception {
    // given:
    WebTestClientRequestSpecification request = given()
        .header("Content-Type", "application/json")
        .body("{"name":"KJSKASVJSGXRLXYKVSXY","
          + ""description":"LXYIOGALHTTSXMUCRIPY","
          + ""speakerIds":["FQJEPDMOAPIMDUPGFCKZ"]}");

    // when:
    WebTestClientResponse response = given().spec(request)
        .put("/sessions/session-id-1");

    // then:
    assertThat(response.statusCode()).isEqualTo(204);
  }

}

This generated test is testing the interaction against our producer. A real request is sent to our service against the defined endpoint and with random non blank strings for the name and description and speaker ids, just as defined in the contract. This should emphasize why it may not always be desired to have a more generic contract as the values are used for the generated test.

Eagle eyed readers may notice, it may be noticed the extends BaseContract in the test. This is required in the setup of Spring Cloud Contracts to define how to configure the producer so it can receive the request sent by the generated test. This makes sense as a contract can create a test, though it has no knowledge of how to start the service.

@SpringBootTest
public abstract class BaseContract {

  @Autowired
  private ApplicationContext context;

  @BeforeEach
  void setUp() {
    RestAssuredWebTestClient.applicationContextSetup(context);
  }
}

This base contract is an implementation detail to this specific framework for this generated test and to complete the story. The finer points of this framework will not be discussed any further.

These generated tests must be fulfilled by the producer as part of the build to ensure that no contracts fail. This is key when developing an API to ensure that defined interactions continue to be fulfilled and that the values and properties do not change by mistake or by accident.

The final part of this story is the generated stub service that can be used by the consumer for testing.

So what is generated?

{
  "id" : "bfd7dd8b-1551-4fc8-b530-231613a201a4",
  "request" : {
    "urlPathPattern" : "/sessions/[a-zA-Z0-9-]+",
    "method" : "PUT",
    "headers" : {
      "Content-Type" : {
        "matches" : "application/json.*"
      }
    },
    "bodyPatterns" : [ {
      "matchesJsonPath" : "$[?(@.['name'] =~ /^\s*\S[\S\s]*/)]"
    }, {
      "matchesJsonPath" : "$[?(@.['description'] =~ /^\s*\S[\S\s]*/)]"
    }, {
      "matchesJsonPath" : "$.['speakerIds'][?(@ =~ /^\s*\S[\S\s]*/)]"
    } ]
  },
  "response" : {
    "status" : 204,
    "transformers" : [ "response-template" ]
  },
  "uuid" : "bfd7dd8b-1551-4fc8-b530-231613a201a4"
}

A mapping file is created that can be used by WireMock. These stub servers are extremely valuable to stand up as individual processes not just for testing but to run alongside the actual service to be able to have a working system whule the actual service is still being built.

Figure 3-8. Schedule and mock Sessions service

When used for testing, as it is herer, we can see a bad request is made. In this example a request is made with the speaker id property being a single value and not an array against this stub service. Again a snippet is shown for brevity to see the whole picture.

@ExtendWith(SpringExtension.class)
@AutoConfigureStubRunner(
    repositoryRoot =
        "stubs://file://location/of/sessions-service/build/stubs",
    ids =
        "com.masteringapi:sessions-service:+:stubs",
    stubsMode =
        StubRunnerProperties.StubsMode.REMOTE
)
class TestSessionsServiceShould {

  @StubRunnerPort("sessions-service")
  int producerPort;

  @Test
  void connect_to_put() {

    final WebTestClient webTestClient = WebTestClient.bindToServer()
      .baseUrl("http://localhost:" + producerPort)
      .build();
    webTestClient
      .put()
      .uri("/sessions/session-id-1")
      .contentType(MediaType.APPLICATION_JSON)
      .bodyValue("{"
        + ""name": "A name","
        + ""description": "A description","
        + ""speakerIds": ["singular-speaker-id"],"
        + "}")
      .exchange()
      .expectStatus().isNoContent();
  }
}

--------------------------------------------------------------------------------
| Closest stub              | Request                                          |
--------------------------------------------------------------------------------
                            |
PUT                         | PUT
/sessions/[a-zA-Z0-9-]+     | /sessions/session-id-1
                            |
Content-Type [matches] :    | Content-Type:
  application/json.*        |  application/json
                            |
$[?(@.['name']              |
    =~ /^s*S[Ss]*/)]    | {"name:" "A name","description:" "A   <<<<<
                            |  Body does not match
                            | description","speakerIds:" "singular-speaker-id",}
$[?(@.['description']       |
    =~ /^s*S[Ss]*/)]    | {"name:" "A name","description:" "A   <<<<<
                            | Body does not match
                            | description","speakerIds:" "singular-speaker-id",}
$.['speakerIds'][?(@        |
    =~ /^s*S[Ss]*/)]    | {"name:" "A name","description:" "A   <<<<<
                            | Body does not match
                            | description","speakerIds:" "singular-speaker-id",}
                            |
---------------------------------------------------------------------------------

API Contracts are valuable for both Consumers and Producers. By defining an interaction both usable tests and stub servers can be generated to validate integrations.

Using contracts promotes Acceptance Test Driven Development (ATDD). ATDD is where different teams can collaborate and come to an agreement on a set of criteria that will solve a problem. Here the problem being solved is the API interaction.

API Contracts Development Methodologies

Now that we understood how contracts work and the value that they provide to the consumer and the producer, we need to know how to use them as part of the development process.

There are two main Contract Development Methodologies:

• Producer Contract testing

• Consumer Driven Contracts

Each methodology has a specific purpose but can be used in conjunction with each other. A similar example is that of the Classicist and Mockist mentioned in unit testing, both methodologies can be used together.

Producer Contracts

Producer contract testing is when a producer defines its own contracts. If starting out on an API program and wanting to introduce contracts to a project then this is a great place to start. New contracts can be created for the producer to ensure that that service fulfils the interaction criteria and will continue to fulfil them. If Consumers are complaining that a producers API is breaking on new releases then introducing contracts can help with this issue.

The other common reason for using Producer contract testing is when there is a large audience for your API. This is defined as an API that is being used outside your immediate organization and by unknown users, i.e external third parties. When developing an API that has a wide public audience it will need to maintain its integrity and though it is something that is updated and improved, immediate feedback and individual feedback will not be applied. A concrete example int the real world is the Microsoft Graph API, it can be used to look at the users registered in an Active Directory Tenant. A consumer may find it preferable to have an additional for preferred name on the Users endpoint of the API. This is something that can be messaged to Microsoft as a suggestion, however, this is not likely to be changed and if the suggestion was seen as a good idea it would unlikely happen quickly. This is something that would have to be weighed up and considered. Is this something that will be useful for others, is it backwards compatible change, how does this change the interactions across the rest of the service?

Here we take the same approach as the example given, with our Schedule API. We do not want consumers making suggested changes to the API that only benefits them. It is external facing and needs to be very solid, most importantly the structure of this API can not suddenly change. Breaking changes involve versioning which be be read about in “API Versioning”.

Consumer Driven Contracts

Consumer Driven Contracts (CDC) is when a consumer drives out the functionality that they wish to see. Consumers submit contracts to the producer for new API functionality and the producer will choose to accept or reject the contract.

CDC is very much an interactive and social process. The owners of the applications that are consumers and producers should be within reach. Recall the contract we defined earlier in “API Contracts”, where the Schedules Service is consuming from the Sessions Service. A new API interaction is desired and a contract is then defined. This contract is submitted as a pull request into the Sessions Service. The maintainers of the Sessions Service can then look at the PR and start reviewing this new interaction. At this point a discussion takes place about this new functionality to ensure that this is something that the Sessions service should and will fulfill and that the contract is correct. While this contract is to be a PUT request, a discussion can take place if this should be in fact a PATCH request. This is where a good part of the value of contracts comes from, this discussion for both parties about what the problem is, and using a contract to assert that this is what the two parties accept and agree to as a solution. Once the contract is agreed, the producer (Sessions service) accepts the contract as part of the project and can start fulfilling it.

As we’ve seen, contracts are required to pass as part of build. Therefore the next release of the Sessions service must fulfill this contract. From contracts the stubs can be generated which the consumer can use for local testing. Both services can develop independently of each other just by using contracts.

Contracts methodology overview

These methodologies should hopefully give an overview of how to use contracts as part of the development process. This should not be taken as gospel as variations do exist on the exact steps. For example, the consumer when writing the contract should also create a basic implementation of the producer code to fulfil the contract. In another example, the consumer should tdd the functionality they require and then create the contract before submitting the pull request. The exact process that is put in place may vary by team. By understanding the core concepts and patterns of CDC the exact process that is put in place is an implementation detail.

If starting out on a journey to add contracts it should be noted that there is a cost to it. This cost is the setup time to incorporate contracts into a project and also the cost of writing the contracts. It is worth looking at tooling that can create contracts for you based on an OpenAPI Specification. At the time of writing there are a few projects that are available, though none are actively maintained so it is difficult to recommend any.

API Contracts Storage and Publishing

Having seen how contracts work and methodologies of incorporating them to the development process the next question becomes where are contracts stored and how should they be published.

There are a few options for storing and publishing contracts and these again depend on the setup that is available to you and your organization.

Most commonly Contracts are stored along side the Producer code in version control (e.g., git). They can then be published alongside the Producer build into a artifact repository such as Artifactory. The contracts are then easily available for the Producer as part of the auto generated tests. Consumers that use the service can retrieve the contracts to generate stubs and can also submit new contracts for the project. The Producer has control over the contracts in the project and can ensure that undesired changes aren’t made or additional contracts are added. The downside to this approach is that in a large organization if can be difficult to find all the API services that use contracts.

Another option is to store all the contracts in a centralized location. A single location for all contracts is very useful as it also serves as a location to see other API interactions that are available. This central location would typically be a git repository, though if well organized could also be a folder structure. The downside to this approach is that unless organized and setup correctly it is possible and likely that contracts get pushed into a module that the producer has no intention on fulfilling.

Yet another option for storing contracts is to use a broker. The PACT contract framework has a broker product that can be used as a central location to host contracts. A broker can show all contracts that have been validated by the producer as the producer will publish those contracts have been fulfilled. A broker can also see who is using a contract to produce a network diagram, integrate with CI/CD pipelines and perform even more valuable information. With the pact broker a producer will be able to pull in submitted contracts to fulfill, it does not pull them in automatically. A broker seems to solve the problems of the previous suggestions, however, there is a setup cost and only the PACT framework has the PACT Broker product.

There are positives and negatives to each approach of storing contracts and it is tempting to think that a Broker is essential to an API Contract Testing program. When starting out in the world of contracts, following the standard of keeping contracts alongside a producer is great approach. It is possible to move to a broker later and should be noted that many users of contracts never use a broker and stick to the basics of contracts alongside the Producer.

API Contract Frameworks

We’ve explained what contracts are, how to use them as part of a project development and how they are stored and distributed. The next step is to choose a contract framework.

The good news is that there are multiple options that are available to choose from. When choosing it is valuable to see the languages that are supported, documentation and most importantly is it going to continue to be developed by the project maintainers. It is always possible to write your own, however, these frameworks handle setups that are common in industry.

As of writing the most popular API contract testing frameworks are:

• Pact.io

• Spring Cloud Contracts

Both frameworks support a range of languages though Pact has a large amount of native support in languages, while Spring Cloud Contracts uses a Docker container to support non-jvm languages.

Pact at its core embraces Consumer Driven Contracts and has been written for this purpose, Spring Cloud Contracts began more aimed at Producer Contract Testing. Both frameworks support both testing methodologies.

As Pact firmly embraces Consumer Driven Contracts, the consumer can define the contract which is a very nice way to develop an API.

It should be noted Spring Cloud Contracts does have partial support for the PACT Broker as it can read the PACT specification.

There is no clear cut rule about which framework is better, unfortunately as is always the case in software the answer is, it depends.

Please note that each contract framework has its own suggestions about publishing and storing contracts. Frameworks can support multiple different ways of storing and publishing so it is important to read the documentation to make an informed decision.

Checklist: Should we adopt API Contracts