What is cURL and why is it all over API docs?

Depending on what version you are running or what you may have downloaded (like Git for Windows and other dev tools) you may already have curl.

Take a look at this post for more info.

Running in a command prompt you can also do the man page sanity check,curl –man.

If you are running Linux, I have a feeling you know what curl is and you probably already have it installed.

????How do I use cURL?Now that we know you have curl installed, you are probably wondering how you actually use it.

Let’s reference how you probably got here in the first place, someone’s API docs.

I’ll use Watson Speech-to-Text on IBM Cloud just because I’ve spent a lot of time there recently, and since we are all friends here, they pay me a nice salary.

Watson Speech to Text Introduction page in API docsSome docs include snippets in a variety of programming languages, and this one is no different, but the first one is curl which is probably intimidating as its not a programming language and certainly doesn’t look like one.

Auth using curl for Watson Speech to Text from API docsThis first set of curl commands you see is just an example of what the rest will look like, a formula for creating them.

So if this doesn’t make any sense to you, keep scrolling.

I always try to find a very simple “GET” that requires a minimal amount of information (ie, no parameters) just so I can see if the endpoint is working and I get a status code back that doesn’t indicate that I’m doing something terrible wrong.

It’s like a confidence building activity with a new API.

Depending on the auth requirements for an API, I might even try to pull this off in a browser since that is just a GET anyway.

Looking at the methods in Speech-to-Text I find “List models”, which requires no parameters and even if I have no models should still respond with the basic “out of the box” models or nothing, who knows.

Excellent, let’s work with that one.

Watson Speech to Text in API Docs for method “list models”In the docs I see an example of what a response should look like.

Navigating to my Speech to Text service, I need my api key (or username/password if I was running an old service) which I can grab from the Manage page.

I’ll copy the API key.

IBM Cloud Watson Speech to Text service manage page with credentialsIn my terminal I’ll need to build something that looks like the example request:curl -X GET -u “apikey:{apikey}” “https://stream.


net/speech-to-text/api/v1/models"Don’t get excited, this API key and entire service has already been deleted.

curl -X GET -u “apikey:vjCxKq8krmb5IX8LBIm-hNLdJwPC3IBs1Pa1jIl0PnEQ” “https://stream.


net/speech-to-text/api/v1/models"Curl execution of “list models”Looks like I get some information on the basic models for each language.

Neat!.It’s not empty and its successful!Pay really close attention here, your API key is just a string value.


If you do, you’ll get an “unauthorized” and be very sad/confused.

Curl execution unauthorized with rogue brackets included in API keyThe response is correct in that you are unauthorized because your API key probably doesn’t include a bracket on the front and the back.

Why would I use cURL and not Postman?.ARC?.Or <insert favorite client>?No one is telling you what you can and cannot use, but as referenced above, curl is fairly standard in its functionality and available across tons of platforms.

There is no UI to get lost in for basic commands with authentication and you can see exactly what’s going on.

But if you find a UI more comforting and familiar, by all means go for it.

To be honest, you don’t even have to use curl.

It’s just there as an option.

Just like the snippets in Go, Python, Java, etc.

Once you are comfortable working with the API, you can start writing the actual code that consumes the API, which for all I know might be some other language entirely.

Whatever you do, let me know when you are building!.Do you use curl?.Do you have a favorite API?.Do you have a method for learning a new API?.Share your tips and tricks below.


. More details

Leave a Reply