.webp)
Most API testing tutorials stop at the first passing test. A real project also needs a base URL that changes per environment, reports someone can read, and a pipeline that runs the suite on every push. Without those, a suite quietly stops being used.
API automation testing means scripting API requests and checking API responses without manual steps. This guide builds a free framework with Java, Maven, REST Assured, TestNG, and GitHub Actions, and every tool is open source. By the end, you will have a project that runs on every push.
What Is API Automation Testing?
API automation testing uses scripts to send API calls to application programming interfaces and check the status code, headers, and body. It sits within software testing, but checks the API layer directly, below the user interface. Runs are fast because there is no browser to load, and stable backend systems protect user experiences.
Types of API Testing Worth Automating
Not every check belongs in the same suite. Automate these layers roughly in this order, cheapest first:
- API Unit Testing: One endpoint or function in isolation.
- API Functional Testing: Checks that a request returns the right data.
- API Integration Testing: Checks that services work together.
- API End-to-End Testing: Checks a full user flow across services.
- API Regression Testing: Checks that the last release broke nothing.
- API Load Testing and Performance Testing: Checks how the API behaves under traffic.
- API Security Testing: A form of Security Testing that probes access control.
How REST, SOAP and GraphQL Differ for Testing
The SOAP vs rest api question decides your tooling, and a GraphQL API adds a third shape. If you searched "rest api what is", the short answer is an API that exposes resources over HTTP URLs, usually returning JSON.
Good rest api design pays off at test time. Consistent resource names, predictable HTTP methods, and correct status codes mean fewer special cases in your suite.
Choosing Free API Testing Tools
Three free api testing tools cover most teams, though the wider set of API automation testing tools is large. Pick by the language your team already writes.
- REST Assured: Assertions written in Java.
- Postman with Newman: Runs collections from the command line. Check compatibility with newer collection formats first.
- Karate: BDD style for mixed-skill teams.
Whichever you choose, API Testing Automation only pays off when Automated Testing runs on every change. This guide uses REST Assured with TestNG because assertions live in code and one Maven command runs everything.
Pick by your team's skills:
- Java team that wants assertions in code: REST Assured with TestNG.
- Testers who already work in Postman: Postman with Newman.
- Readable BDD scenarios without writing Java: Karate.
Step-by-Step Framework Setup
A working test automation framework has six parts, namely tests, request specs, utilities, config, test data, and a suite file. Lay them out before writing test code.
src/test/java/api/base request and response specs
src/test/java/api/tests test classes
src/test/java/api/utils config reader, helpers
src/test/resources/config environment properties
src/test/resources/data payloads and JSON schemas
testng.xml suite definitionStep 1: Install Java, Maven, REST Assured, and TestNG
Install Java 17, a long-term support release that works with current REST Assured and TestNG, plus a recent Maven. Add these Maven dependencies to pom.xml, then run mvn clean test-compile to confirm the build. Check Maven Central for newer versions before you copy these numbers.
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>rest-assured</artifactId>
<version>5.5.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testng</groupId>
<artifactId>testng</artifactId>
<version>7.10.2</version>
<scope>test</scope>
</dependency>Step 2: Write Your First REST API Test with REST Assured and Java
Here is a minimal rest api example against JSONPlaceholder, using the GET method. Other HTTP Methods follow the same pattern. Statically import io.restassured.RestAssured.*, org.hamcrest.Matchers.* and io.restassured.http.ContentType.
@Test
public void getPostReturnsExpectedFields() {
given().baseUri("https://jsonplaceholder.typicode.com")
.when().get("/posts/1")
.then().statusCode(200)
.contentType(ContentType.JSON)
.body("id", equalTo(1));
}Run it with mvn test and it should pass. Then stretch it a little:
- Assert the response codes, content type, and one body field.
- Change 200 to 201 and read the failure message, so you know what a failing test looks like.
- Add edge cases, such as a missing ID or an empty body.
- Write these as small unit tests, then group them into test scenarios.
Step 3: Manage Test Data and Environments
Hard-coded hosts break first, usually the day someone needs to run the suite against another environment. Moving config out of code fixes that early and costs very little. Put base.url=https://jsonplaceholder.typicode.com in config/dev.properties, then add a small reader:
public class ConfigReader {
private static final Properties props = new Properties();
static {
String env = System.getProperty("env", "dev");
try (InputStream in = ConfigReader.class
.getResourceAsStream("/config/" + env + ".properties")) {
props.load(in);
} catch (Exception e) { throw new RuntimeException(e); }
}
public static String get(String key) { return props.getProperty(key); }
}The test now reads its host from config. A TestNG @DataProvider then runs it against several IDs:
@DataProvider(name = "postIds")
public Object[][] postIds() { return new Object[][] {{1}, {2}, {3}}; }
@Test(dataProvider = "postIds")
public void getPostById(int id) {
given().baseUri(ConfigReader.get("base.url"))
.when().get("/posts/" + id)
.then().statusCode(200).body("id", equalTo(id));
}- Create one properties file per environment.
- Switch with mvn test -Denv=staging; the reader defaults to dev.
- Keep authentication tokens in environment variables or GitHub secrets, never the repo.
Step 4: Add Assertions and Reporting with TestNG
Keep two assertion layers apart, because they answer different questions. REST Assured matchers such as body("id", equalTo(1)) check API responses inline, while TestNG's Assert checks values you extract and compute. Check response behavior too, not just the body:
- Status code and content type.
- Headers you rely on, such as caching headers.
- Response time, with a generous limit.
- Error messages for bad input.
For JSON schema validation, add json-schema-validator at the same version as REST Assured, and keep a schema file at data/post-schema.json. A response schema check fails the moment a field is renamed or changes type, which makes schema validity the cheapest guard against shape changes.
<dependency>
<groupId>io.rest-assured</groupId>
<artifactId>json-schema-validator</artifactId>
<version>5.5.0</version>
<scope>test</scope>
</dependency>{
"type": "object",
"required": ["id", "title"],
"properties": {
"id": { "type": "integer" },
"title": { "type": "string" }
}
}// import static io.restassured.module.jsv.JsonSchemaValidator.matchesJsonSchemaInClasspath;
.then().statusCode(200)
.body(matchesJsonSchemaInClasspath("data/post-schema.json"));For reporting, point Surefire at testng.xml so mvn test runs your suite and writes an HTML report to target/surefire-reports/index.html. Allure or Extent Reports are optional upgrades when the default report stops being enough.
<plugin>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.2.5</version>
<configuration>
<suiteXmlFiles>
<suiteXmlFile>testng.xml</suiteXmlFile>
</suiteXmlFiles>
</configuration>
</plugin>Step 5: Run Tests in a Free CI/CD Pipeline with GitHub Actions
Yes, you can run API tests in CI for free. Public repositories on GitHub Actions are free, and private repositories get a monthly allowance of free minutes on the free plan.
CI/CD pipelines are where a framework proves itself. A CI pipeline on every pull request catches regressions before merge.
name: api-tests
on:
pull_request:
push:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: '17'
cache: maven
- run: mvn -B test -Denv=dev
env:
API_TOKEN: ${{ secrets.API_TOKEN }}
- uses: actions/upload-artifact@v4
if: always()
with:
name: test-report
path: target/surefire-reportsThat file is the whole github actions api tests setup. It checks out the code, installs Java, runs the suite, and uploads the report, even when tests fail.
Adding Contract and Security Checks to Your Framework
Functional tests pass happily while a renamed field breaks every consumer. Two extra layers close that gap, and both are cheap to add once the base framework runs.
Contract Testing to Catch Breaking Changes
Contract testing checks that an API still honours the response shape its consumers expect. It catches a breaking change before the consuming team does.
- Reuse the schema check from Step 4 and run it on every build.
- With several consuming teams, look at Pact for consumer-driven contracts, later rather than first.
Basic API Security Tests for Common Risks
API security risks are not only a job for specialist products. The OWASP API Security Top 10 lists broken object-level authorisation first, so three baseline API Security Testing checks, tied to your security protocols, catch a lot:
- Request another user's record with your token and expect 403 or 404.
- Call a protected endpoint with a missing or expired authentication token and expect 401.
- Call an admin route as a standard user and expect 403.
These are baseline checks, not a penetration test. Each one is a short REST Assured test that sends the request and asserts the status code.
Best Practices for Maintaining the Framework
A suite stays useful only while people trust it. These API testing best practices keep it that way:
- Make every test create and clean up its own data, so tests can run in any order.
- Keep hosts and credentials out of code.
- Retry only known network failures, and log each retry, because blanket retries hide real bugs.
- Store tests in the same repo as the service code, so changes ship together.
- Track cases and results in test management software.
- Review quarterly and delete tests for endpoints that no longer exist.
How Frugal Testing Helps You Scale API Test Automation
Frugal Testing builds API test automation inside client repositories and connects it to their CI pipelines. Our test automation services suit teams that have outgrown a single-person framework or need broader test scenarios across many services. We set up the framework, reports, and pipeline so your team starts from a working base.
When releases wait on test capacity, QA outsourcing is often quicker than hiring and onboarding, and our QA outsourcing services cover both the build and the handover. Our engineers hand over a runbook and walk your team through the suite, so you can maintain and extend it without us.
What Our API Testing Engagement Looks Like
Every engagement follows the same four steps, so you know what to expect from week one. Each step ends with something you can review.
- We audit your endpoints and specs.
- We build the framework in your repo.
- We connect CI and reporting.
- We hand over with a runbook.
At the end, the repo, the pipeline, and the runbook are yours. Your team can run and extend the suite without us.
.webp)
Conclusion
API automation testing is less about the first green test than the months after it. The free stack gives you a working base: REST Assured and TestNG for the tests, schema and security checks for safety, and GitHub Actions to run everything on every push.
What keeps the suite useful is routine. Keep config out of code, read the report after every run, and review the tests every quarter. Delete tests that no longer earn their place, because a smaller suite that people trust beats a larger one they ignore.
People Also Ask (FAQs)
Q1. What is API security testing?
Ans: API security testing checks that an API resists misuse, such as broken authentication, missing authorisation, and data exposure. It sends unexpected requests and confirms the API refuses them.
Q2. Can I run REST Assured tests in parallel?
Ans: Yes. Set the parallel attribute to methods and add a thread-count in testng.xml. Keep tests independent, so they do not share data, and start with two or three threads.
Q3. How do I assert on values that change, like timestamps or IDs?
Ans: Assert fixed fields exactly and use matchers such as notNullValue() for generated ones like timestamps. Extract IDs from one response and reuse them in the next request.
Q4. How do I send an authentication token with REST Assured?
Ans: Use the auth().oauth2(token) method for OAuth2 access tokens, or add an Authorization header yourself. Read the token from an environment variable so it never appears in code.
Q5. How do I see the request and response when a test fails?
Ans: Call RestAssured.enableLoggingOfRequestAndResponseIfValidationFails() once in a setup method. REST Assured then prints the full request and response only for failing tests, which keeps CI logs short.
.webp)
