Introducing embedcurl.com: Interactive curl command widgets for your web site, blog or API documentation.
If you consume a lot of APIs like we do, you'll inevitably come across API documentation with examples using the curl command line tool for making HTTP requests. Curl is the closest thing we have to a universally available API client, making it great for documentation. There's (usually) nothing to install, it works the same everywhere, and commands can be represented in plain text.
There are a few downsides however. If you're unfamiliar with curl, the syntax can be opaque and daunting. Longer commands suffer from readability issues and are difficult to visually parse. Executing the request takes you out of the browser.
Embed curl is the latest addition to our Community Projects initiative. The site allows you to convert any curl command into an interactive, prettified widget you can embed in your blog, web site or API documentation. Think of them as Gists for curl.
Embed curl turns this:
curl -X POST -i https://someapi.io/api/v1/customers/5/events \ -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \ -d name=purchased \ -d data[price]=23.45 -d timestamp=1359389415
curl -i -X POST https://someapi.io/api/v1/customers/5/events \ -u YOUR-SITE-ID-HERE:YOUR-SECRET-API-KEY-HERE \ -d name=purchased \ -d data[price]=23.45 -d timestamp=1359389415
How it Works
Once the script has been placed on your page, any content wrapped in <pre class="embedcurl">...</pre> will be swapped out with the interactive widget you see above. The web site will help you generate the required markup you need.
Why stateless? In most API docs, dynamic values like API keys are inserted into the curl examples if the viewer is signed into their account. Using this method means we don't have to store those credentials or require you to create the embeds ahead of time.
Key Embed curl Features
Easier Copy and Paste
Copying and pasting multiline curl commands from a web browser doesn't always work right. Embed curl generates a single-line (easier to edit once pasted!) copy and paste function to help your visitors get the command entered faster.
I can never remember what all the flags that curl supports are. Embed curl saves you a trip to the man page by offering tooltips explaining what each flag means by hovering over the flag.
Send to Hurl.it
Hurl.it is another one of our community sites that makes it easy to make API requests from the browser. Embed curl provides links for every embed to hurl.it with the values from the curl command pre-populated. This is great for people without curl installed, or those who just want to quickly check out what the command will do without running it directly.
See it on Loader.io
Our friends over at loader.io integrated Embed curl into their API docs in just a few hours. You can see an example here.
We want your feedback!
Do you have a suggestion for how Embed curl could be better? Run into issues with how your command is being parsed? We want to hear from you!