Let’s start with a simple “Hello, World!” request that fetches your LiquidPlanner account details.

Throughout this document, we’ll provide examples using curl. We use curl because it is available across platforms and assumes no knowledge of any particular programming language.

Examples will look like:

% command arg1 arg2 ... argN
... command output ...

where the ”%” is your command prompt; long command lines may be continued to the next line by ending the line with a backslash. Type the command followed by its arguments, and hit enter. You should get output similar to that in the example (though we’ve reformatted, truncated, or omitted example output for readability).

Store Defaults in a Config File

Create a config file similar to the following, using your login information:

% cat ~/.liquidplanner_curl
compressed
user: api_user@example.com:api_password
-H "Content-Type: application/json"
write-out: "\nStatus: %{http_code}\n"

This tells curl to ask for and to handle a compressed response, provides your credentials, specifies that POSTed data is JSON-encoded (rather than form-encoded), and instructs curl to output the HTTP status code after the response body (which is useful for troubleshooting).

To keep your password secure, make the config file readable only by you (using chmod on Linux, Mac OS X, etc.):

% chmod 600 ~/.liquidplanner_curl

On Windows, use the file properties pane (or the “cacls” command).

Alternatively, omit the password from the file (including only your email address), and you’ll be prompted for it each time you run curl.

Run the Request

Now tell curl to read configuration from this file, and request your account info:

% curl -K ~/.liquidplanner_curl https://app.liquidplanner.com/api/account 
{
  "avatar_url": "/images/avatars/none.gif",
  "created_at": "1977-09-10T00:00:01+00:00"
  "created_by": 23,
  "email":      "api_user@example.com",
  "first_name": "Brett",
  "id":         23,
  "last_name":  "Bender",
  "timezone":   "US/Pacific",
  "type":       "Member",
  "updated_at": "2010-01-01T00:00:01+00:00",
  "updated_by": 23,
  "user_name":  "brett",
}
Status: 200

For brevity in subsequent examples, we write curl where we really mean:

curl -K ~/.liquidplanner_curl

so that your configuration file is used. You may want to create a command alias such as lpcurl for the above; it will save you some typing.