Blog

API blog: notes from the catalog

The GLOBUS.App API blog collects practical notes on API design, data quality and the parts of shipping software that rarely make a changelog. Every post comes from a question that appeared while building or documenting an endpoint.

Start with why small APIs beat one big integration, or read why a User-Agent is not proof. The note on response formats explains the JSON and plain text contract.

What the API blog covers

Three kinds of posts appear here. The first is a design note about a choice that affects an interface: a response shape, a timeout, a field that looks harmless until a client depends on it. The second is a guide to a check or a data source, with the cases where the answer is incomplete. The third is a short report from operating the catalog, such as a rate limit that was too tight or a cache that hid a change for too long.

The posts avoid launch announcements and roadmap promises. A note stays useful after the next release because it describes a problem and a decision, not a feature list.

Guides for each endpoint

Every API has a longer guide in the API guides category. A guide covers a real scenario, the response fields, the limits and the links to the endpoint page. Use it when you need more than the parameter table, for example when you have to decide what to do with a Tor flag or how to treat an email address that the mail server will not confirm.

The notes in the notes category are shorter. They take one idea and explain the trade-off, usually with a small example. Both categories link to the endpoint, so you can move from the explanation to the request without searching.

How to read the guides

Each guide starts with the question the endpoint answers and the shape of the response. Then it covers the edge cases: a missing parameter, a value the provider does not know, a result that is a snapshot rather than a live fact. The last sections list the limits and the related endpoints.

If you only need the URL and the parameter names, open the API page. If you need to write a policy around the answer, read the guide and the linked source. The API blog does not replace the documentation; it explains why the documentation looks the way it does.

What makes a good note

A useful note names the situation, the decision and the cost of the other choice. "Use a timeout" is weak advice. A note that explains why a five-second timeout fits one endpoint and breaks another gives the reader something to copy into a design review.

The API blog follows that rule for every topic. A post about bot detection shows a request that a crawler makes and a request that a browser makes, then explains which signal separates them and where the signal fails. A post about a placeholder API shows the layout problem first: a card with no image, a test page with no text, and the moment when a hard-coded value stops being enough.

Readers come from search with one question. The post answers it in the first screen, then adds the context that makes the answer hold when the input changes. That structure also keeps the API blog readable for someone who lands on a guide from an endpoint page.

Notes and guides

The API blog uses two formats. A note takes one idea and explains the trade-off in a few screens. A guide follows an endpoint from the first request to a policy, with the response fields and the limits. The category page makes the difference visible, and every post links to the endpoint it describes.

A note can become a guide when readers ask the same question in different words. The API blog keeps the older post and links the new one, so a search result still lands on an answer. That is more useful than a redirect to a page that covers five topics at once.

Search and archives

The API blog is indexed by category and by date. A reader who searches for a specific error message should find the guide that mentions it, so the text uses the field names and the parameter names from the documentation. The search page covers the posts and the guides, and the API collection covers the endpoints.

Old posts stay online. A post about a limit that changed gets an update at the top rather than a deletion. The API blog is a record of decisions, and a removed decision leaves a gap for the next reader.

How posts are edited

An editor reads a draft against the endpoint page before it goes live. The field names have to match, and the examples have to run. A post that changes a number needs a source, and a post that changes a recommendation needs a note about the version it applies to.

The API blog does not publish a post to fill a calendar. A month without a note is fine if the drafts are weak. The archive is more useful when every entry has a decision behind it, and the reader can see why the post exists.

The API blog keeps the category list short. A new category appears when three posts share a subject, not when one post needs a label. A reader should be able to scan the list and know where a guide lives without opening every post.

Every card in the feed shows the same facts: the title, the date, the category and the first lines of the post. That is enough to choose a guide without opening it. A card that needs a badge or a progress bar is a sign that the post has grown into a series.

Corrections and topics

When a post turns out to be wrong, the correction goes into the post with the date of the change. A topic that needs a longer answer becomes a guide. If a question is missing from the API blog, send it through the contact page.

For a quick lookup, open the API collection. For the full reference, use the documentation.