Blog·Note·

Group the catalog by what you have

An email address, a place, or a coordinate is a useful place to start when choosing an API.

The API catalog used to group things under labels such as Locate, Validate, and Decode. Those words describe what the endpoints do, but they make you classify your problem before you can find the endpoint.

If you have an email address, you know that much already. You might still be figuring out whether you need to check its format or find out whether the mailbox can receive mail.

I changed the groups to start with what you have: a name or number, a domain, an IP or User-Agent, a place, a coordinate, a code. Within each group, an example shows the input and the kind of answer that comes back.

That makes the catalog useful even when you don't know the name of the product yet. You can start with a coordinate and see the different questions you can ask about it. Or start with an email address and find the lookup without deciding whether parsing it counts as validation or decoding.

The documentation can still organize reference material by the operation. The API catalog is where you're choosing what to use, so it starts one step earlier.