Hoppscotch, an API client that opens in a second

Hoppscotch, an API client that opens in a second

API clients grew over the years from a tool for sending requests into a platform with an account, synchronisation, workspaces, and an updater. Hoppscotch goes the other way: you open a browser tab, send a request, and see the response.

It is an open source project you can run on your own infrastructure, and for individual work it runs without an account. Beyond HTTP requests it handles GraphQL, websockets, server sent events, and a publish subscribe protocol.

Why the browser matters

Running in a browser is not merely convenient. It changes two practical things.

The first is time to work. A tool needing no installation and no login is available immediately, including on somebody else's computer and on a machine where you lack rights to install software.

The second is where the request originates. A browser client sends it from your browser, so origin policy and local network access apply. That helps when testing intranet services and hinders with services lacking the right headers. A proxy forwarding the request, run locally or supplied by the service, serves the latter.

Understanding that difference matters, since the commonest first use problem is an origin policy error that looks like a tool failure and is normal browser behaviour.

Collections and environments

Requests group into collections, and changing values live in environments. That split is common to every tool in this category and it decides whether a collection is still useful a month later.

<<baseUrl>>/api/orders/<<orderId>>

Authorization: Bearer <<token>>

Local, staging, and production environments then differ only in values rather than in request content. Switching environment with one selection switches every request in the collection.

Two rules keep it from drifting. First: no address is hardcoded, not even in a request written for five minutes' use, since such requests last for years. Second: secrets go only into environments marked private, never into a collection heading for a repository.

Collections export and import, including from other tools' formats. That matters when moving existing work, since a collection built over two years is usually the main reason teams stay with a tool they dislike.

Pre and post request scripts

Requests are rarely independent. Usually you must log in first, take a token, and use it in later calls.

pw.env.set("token", pw.response.body.access_token)

pw.test("Status 200", () => {
  pw.expect(pw.response.status).toBe(200)
})

pw.test("Order has items", () => {
  pw.expect(pw.response.body.items).toBeType("array")
  pw.expect(pw.response.body.items.length).not.toBe(0)
})

The post response script stores the token into the environment, so later requests use it automatically. That pattern covers most needs and lets a whole collection run with one command, with no manual copying.

Tests in the same place turn a collection into a simple check suite. It does not replace tests in code, and it suffices to verify that an interface answers as before after a deployment.

A pre request script helps with values computed on the fly: a signature, a timestamp, a correlation identifier. Keep it short, since a thirty line script in an API client signals that the job belongs in code.

pw.env.set("timestamp", String(Date.now()))
pw.env.set("correlationId", crypto.randomUUID())

const base = pw.env.get("baseURL")
pw.env.set("fullAddress", pw.env.resolve("<<baseURL>>/api/v2"))

The three read methods differ in a way worth knowing. A plain read returns the value as stored, including any references to other variables. A resolving read substitutes those references, and a separate function expands a whole template passed as text. Confusing them ends with an address containing literal angle brackets instead of a value.

Running from the command line

A collection run by hand suits diagnosis rather than guarding quality. Running it in a build pipeline serves the latter.

npm i -g @hoppscotch/cli
hopp test collection.json -e environment.json

In a build pipeline it looks like any other step, and a non zero exit code stops the deployment.

- name: Interface tests
  run: |
    npm i -g @hoppscotch/cli
    hopp test collections/public.json -e environments/production.json

That arrangement gives simple post deployment interface tests: the collection walks the most important paths and reports an error when a response changes. It catches the commonest class of problem with back end changes, meaning a field that disappeared or was renamed.

It requires keeping the collection in the repository rather than only in a user account. A file in the repository goes through review, has change history, and works for everyone, while a collection in somebody's account leaves with that person.

Working with GraphQL

GraphQL queries get a dedicated view here, since they differ from ordinary requests enough that a shared form would be awkward.

query GetOrder($id: ID!) {
  order(id: $id) {
    number
    status
    items {
      name
      quantity
    }
  }
}

Variables go in separately, and the tool pulls the schema from the endpoint, so it suggests available fields and raises an error before you send a query for a field that does not exist. That is the most useful part of working with this protocol, since documentation is often incomplete while the schema is always current.

Mind the difference in error handling. A GraphQL response can carry a two hundred status and errors in a separate field at once, so a test checking only the status passes a query that returned nothing.

pw.test("No GraphQL errors", () => {
  pw.expect(typeof pw.response.body.errors).toBe("undefined")
})

With a GraphQL back end, keep a schema fetching query in the collection. Run after deployment it catches a removed field before the front end notices.

Sockets and event streams

Beyond ordinary requests the tool handles persistent connections, which helps with notification driven applications and with streaming model responses.

The socket view lets you open a connection, send a message, and watch everything arriving from the other side. That solves the most tiresome stage of diagnosing such connections, where without a tool you must write your own test page.

Server sent events get a separate view showing the stream live. On an endpoint streaming a model response, built with Hono for instance, that lets you check whether chunks genuinely leave piece by piece rather than all at once at the end.

The third supported protocol is publish subscribe, used in telemetry and device work. That is a niche application, though having all three protocols in one tool saves installing three separate ones.

Self hosting and pricing

Self hosting is the main advantage here over closed tools. Requests, collections, and secrets stay on your server, which for interfaces touching personal data is sometimes a requirement rather than a preference.

Remember the costs invisible in a price list: a server, updates, backups, and authentication wired into your existing system. For a five person team those costs usually exceed the subscription; at fifty the proportion inverts.

Hoppscotch against the alternatives

The last row is unfairly overlooked. One request is checked faster with a terminal command than by opening anything, and for scripts it is the only sensible option. A graphical client earns its keep when reading long responses, working with a collection, and sharing it with a team.

Choosing between the first two rows comes down to a question about storage format. If you want collections in the repository as reviewable files, the second row is built for that. If browser access and shared team work in one place matter, the first.

A collection as interface documentation

A well maintained collection is the most current interface documentation a team has to hand. Documentation written separately ages within a month, while a collection ages only once it stops working, which somebody notices immediately.

For that to hold, a collection needs a few things beyond the requests themselves. A description on each request saying what it does and when it is called. Sample values in variables so a newcomer can run them without asking. Requests covering error cases too, since an error code and the shape of an error response are part of the contract.

Order the requests so somebody can walk them top to bottom and see the whole flow: log in, create a resource, read, modify, delete. Such a collection explains an interface better than a paragraph of prose.

Bug reports are a separate benefit. A request reproducing the problem, attached to the report, saves a round of questions about how exactly somebody called the interface.

Authentication and secrets

Most interfaces require a token, and how you obtain one is often the most tiresome part of the work.

The tool handles standard authentication schemes in a dedicated tab, so there is no header to build by hand. With a redirect based flow, remember that some steps happen in the browser and need a correctly configured return address on the identity provider's side.

The practical pattern with short lived tokens runs like this: a separate login request stores the token into the environment, and every other request uses the variable. Refreshing then takes one click rather than copying values around.

Keep secrets in variables marked secret, which stay out of exports. That distinction matters when sharing a collection: you want to pass on the request structure rather than your production token. In team work, settle that everyone uses their own credentials, since a shared token makes it impossible to tell who performed a given operation.

Common mistakes

The first is hardcoded addresses in requests. The collection stops working after an environment change, and fixing twenty requests by hand takes longer than setting a variable at the start.

The second is secrets in a collection exported to a repository. A token typed into a header stays in the change history and needs rotating once discovered.

The third is treating an origin policy error as a tool failure. It is normal browser behaviour, resolved by a proxy or by the right headers on the service side.

The fourth is keeping collections only in a user account. Knowledge of how to call the interface then leaves with whoever leaves the team.

The fifth is elaborate scripts inside the client. Logic grown to dozens of lines belongs in code with tests rather than in a tool without version control.

The sixth is testing only the happy path. A collection checking only situations where everything works will not catch a change in error handling, and that is where most surprises hide.

FAQ

Is Hoppscotch free?

The browser version for individual work is free and needs no account. The community version for self hosting is too. The paid cloud plan is called Organization and costs eight dollars per person monthly billed monthly or six billed annually. The self hosted Enterprise edition has a published price too: nineteen dollars per person monthly or one hundred and ninety per person yearly.

How does it differ from Postman?

It is far lighter, runs in a browser without installation, and can be hosted on your own server. Postman carries more features and integrations but requires an account, weighs more, and costs noticeably more for a team. For everyday request sending the capability difference is slight.

Does it support GraphQL?

Yes, with a dedicated view for queries and schema browsing pulled from the endpoint. It also handles websockets, server sent events, and a publish subscribe protocol, so it covers most protocols encountered beyond plain HTTP.

Can a collection run in a build pipeline?

Yes, through a command line tool taking a collection file and an environment file. That lets you check after deployment whether the interface's key paths answer as before, catching compatibility breaking changes.

When is something else the better pick?

When a team wants collections as repository files and work without a server side service, Bruno is built for that. For a one off check of a single request a terminal command is often faster, and for an elaborate process in a large organisation a tool with a bigger integration set wins.

Documentation sits on the project site, and self hosting instructions in the self host guide.