REST / OpenAPI

What Is REST?

REST (Representational State Transfer) is an architectural style for building web services, introduced by Roy Fielding in his 2000 doctoral dissertation. Rather than defining a strict protocol, REST describes a set of constraints that, when followed, produce scalable, loosely-coupled systems. Today, REST is by far the most common approach to building public and internal APIs.

The core idea is simple: every piece of data your API exposes is a resource, identified by a URL. To interact with a resource, clients use standard HTTP methods — GET to read, POST to create, PUT or PATCH to update, and DELETE to remove. The server responds with a representation of the resource, almost always as JSON.

REST APIs are stateless: each request from a client contains all the information the server needs to process it. There are no sessions or server-side state between calls. This makes REST APIs inherently scalable — any server in a cluster can handle any request, and load balancers can distribute traffic freely.

Because REST relies on standard HTTP, it works with every programming language, every platform, and every network tool. You can test a REST API with nothing more than curl or a web browser. This universality is why REST dominates the API landscape, powering everything from social media feeds to financial trading systems.

What Is OpenAPI / Swagger?

OpenAPI (formerly known as Swagger) is a machine-readable specification format for describing REST APIs. An OpenAPI document — written in YAML or JSON — lists every endpoint, HTTP method, request parameter, request body schema, response format, authentication method, and error code your API supports. Tools can then generate documentation, client SDKs, server stubs, and test suites directly from the spec.

The OpenAPI Specification is maintained by the OpenAPI Initiative, a Linux Foundation project. Version 3.1 (the current standard) aligns fully with JSON Schema, making it easy to validate requests and responses. If you have ever visited a Swagger UI page with interactive "Try it out" buttons, that page was generated from an OpenAPI document.

How REST Works with Opsalis

REST is the native language of the Opsalis platform. If your API already speaks REST and has an OpenAPI spec, integration is as straightforward as it gets.

1. Owner uploads an OpenAPI spec (YAML or JSON) via the handler web dashboard. The handler validates the spec and registers endpoint metadata with the Opsalis catalog.
2. Handler calls the API using standard HTTP methods. When a consumer request arrives, the owner handler maps it to the appropriate REST endpoint, forwards the HTTP call to the real API server, and captures the JSON response.
3. Consumer gets an auto-generated OpenAPI spec from the catalog — regardless of the owner's underlying protocol. For REST owners, the consumer spec is essentially a clean mirror of the original.

Demo API: King James Bible

This demo uses the King James Bible API — 31,102 verses across 66 books, 1,189 chapters. Query by book, chapter, and verse. Search the full text. A rich, real-world dataset that demonstrates REST pagination, filtering, and nested resource lookups.

Code Example

Fetch a specific verse (John 3:16)

Response

Search for verses containing a keyword

REST at a Glance