# The Java API Web Service Cheap Seats

> APIs let systems share data through a stable contract. This 2015 primer explains why with Halloween candy, plus the free Java stack I used.

Canonical: https://mikereams.com/writing/the-java-api-web-service-cheap-seats

Published: December 18, 2015  
Author: Mike Reams (https://mikereams.com/about)  
Topics: [Web Development](https://mikereams.com/writing/topics/web-development), [Development](https://mikereams.com/writing/topics/development)  
Tags: API, Web Service

![The Java API Web Service Cheap Seats](https://mikereams.com/writing/d376ef977055efa12a1077783dcacb29dc9c39db-500x286.jpg)

*Written in 2015. The analogy holds up; the stack has moved on. The note at the end says what I'd use today.*

## Why APIs

In 2015 the industry was moving everyone toward APIs, not least because of the Internet of Things. An API wraps an IT function in a reusable, portable interface, and every reuse lowers the cost of the next solution.

Picture the next time your favorite project manager asks how long it will take to automate warming up the CEO's projector a minute after their car pulls into the parking deck — and you don't laugh out loud.

## The Halloween-candy analogy

An API is you handing out the Halloween candy yourself, so there's enough for everyone, instead of leaving the bowl on the porch and letting the kids take what they think they need. Leave the bowl out and next thing you know the porch light is off, and you're explaining to your wife that a big kid in a robber costume took all the candy and broke the flower pot on the way out.

So why put another interface in the way?

- **Controlled access to data:** the candy only comes out through you.
- **Cleaner traffic:** you decide who comes up the steps.
- **Room to adapt:** you can see the greedy trick-or-treaters coming and plan for them.
- **Faster delivery:** you can handle 200 trick-or-treaters a night instead of 20.

## The standards

- **API** (Application Programming Interface): a published set of rules for how one piece of software asks another for something.
- **REST** (Representational State Transfer): an architectural style for APIs — stateless, with a uniform interface, usually over HTTP.
- **HTTP:** the protocol underneath. Its verbs map to what an API does: GET retrieves, POST creates, PUT updates, DELETE removes.
- **JSON** (JavaScript Object Notation): the text format most APIs use to exchange data.

## The free stack, 2015

Everything here was free, with a large community behind it, so there were no license costs to get started.

- **Java SDK and runtime:** the foundation. Java 8 was replacing Java 7, which stopped getting public updates in April 2015.
- **Eclipse:** the IDE.
- **Maven:** builds the project and manages its dependencies.
- **Tomcat:** the servlet container that serves the API over HTTP, on your PC or a server.
- **Jersey:** the reference implementation of JAX-RS, Java's standard API for RESTful services.
- **Swagger:** describes the API, so you get interactive documentation and generated client SDKs.

## If I built it today

Same ideas, newer tools: a current Java LTS (21 or 25), Spring Boot or Quarkus instead of assembling Tomcat and Jersey by hand, Jakarta REST in place of JAX-RS, and an OpenAPI 3 spec where Swagger 2 used to be. For the OpenAPI side, see [Documenting a Next.js API With OpenAPI and Swagger UI](https://mikereams.com/writing/next-js-with-swagger-3-setup) — the spec part applies to any stack.