Skip to main content

HTTP request examples using curl

· 3 min read
Mattias Kindborg
Mattias Kindborg
Developer Offering

Why are we using curl in our API documentation?

When documenting HTTP APIs, we sometimes use HTTP semantics - currently defined in RFC 9110. It's precise, it's standardized, and it's... well, let's be honest, it can be a bit intimidating if you're new to HTTP APIs.

Here's a typical example of how we describe a request in VAPIX® using HTTP semantics:

POST /axis-cgi/basicdeviceinfo.cgi
Host: <servername>
Content-Type: application/json

{
    "apiVersion": "1.0",
    "method": "getAllProperties"
}

For experienced developers, this is crystal clear. But for someone just getting started, or someone who primarily works in a specific programming language, there's a gap between seeing this specification and actually making the request work. You know what needs to be sent, but how do you actually send it?

There's also the matter of authentication. Since authentication is often ubiquitous across a collection of endpoints, we usually don't include authentication headers in every single example. This makes the examples less copy-paste friendly, as you need to figure out and remember to add the authentication part yourself.

Enter curl​

This is where curl comes in. If you've worked with HTTP APIs for any length of time, you've probably encountered curl. It's the Swiss Army knife of HTTP requests - a command-line tool that's been around since 1996 and is available on virtually every platform imaginable.

The beauty of curl is its immediacy. You can copy a curl command, paste it into your terminal, replace some placeholders, run the command, and see results right away. No need to set up a project, configure dependencies, or write boilerplate code. It's the fastest path from "I want to try this" to "I see the response".

In our documentation, HTTP request examples are from now on displayed using a tabbed interface with two options. The first tab shows the request using curl, and the second shows the request using HTTP semantics.

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/axis-cgi/basicdeviceinfo.cgi" \
  --data '{
    "apiVersion": "1.0",
    "method": "getAllProperties"
}'

Suddenly, it's not just a specification - it's something you can actually run and experiment with.

Please note that in the curl example, the --anyauth flag automatically selects the most appropriate authentication method supported by the device, simplifying the process of making authenticated requests.

More than just documentation​

There's another benefit we haven't mentioned yet: curl commands are easily convertible to other languages and tools. Many developers use curl as a starting point, then translate those commands into Python requests, JavaScript fetch calls, or whatever their preferred language happens to be. Some tools even automate this conversion.

The best of both worlds​

We're not abandoning HTTP semantics - they remain the authoritative specification of how our APIs work. But by complementing them with curl examples, we're making our documentation more accessible and immediately useful.

Our goal has always been to help you build great solutions with Axis products. Sometimes that means providing precise technical specifications. And sometimes it means giving you something you can copy, paste, and run in the next five seconds. Why not both?