Docs‎ > ‎REST APIs‎ > ‎

curl Example

curl is a very popular command-line utility to interact with various network protocols, including HTTP and HTTPS. It can therefore be used to interact with a REST API. Here are a few examples of using curl with Espresso Logic:

Retrieving some data

curl -H "Authorization: Espresso MyAPIKey:1" https://eval.espressologic.com/rest/acme/myproject/v1/widgets

This request includes one HTTP header named Authorization. It identifies and authenticates the call.
  • MyAPIKey is the API key you need to make any calls. You can create your own API keys and give them whatever permissions you require.
  • https://eval.espressologic.com/rest is the base URI, in this case for an evaluation Espresso Logic account. This will depend on your type of account.
  • acme is the name of your account.
  • myproject is the name of your project
  • v1 is the name of your API version
  • widgets is the name of your resource, which could either be a table, or a resource defined for one or more table.

The response (assuming there's only one widget in the database, or at least that can be read by this API key) would be something like:

[
 {
    "@metadata": {
      "href": "https://eval.espressologic.com/rest/acme/myproject/v1/widgets/1002",
      "checksum": "R:2b26c827f961d5db"
    },
    "ident": 1002,
    "name": "Demo widget",
    "price": 123.45
  }
]

The @metadata sub-object contains all the information required by Espresso Logic for context. You'll normally need to send it as part of the object when interacting with Espresso Logic.

Filtering

GET provides filter and sort. Note that special characters must be URL-encoded:

# Filter: name like '%Hammer%'
curl -H "Authorization: Espresso MyAPIKey:1" https://eval.espressologic.com/rest/acme/myproject/v1/widgets?filter=name%20like%20%27%Hammer%%27

# Sort: name desc
curl -H "Authorization: Espresso MyAPIKey:1" https://eval.espressologic.com/rest/acme/myproject/v1/widgets?order=name%20desc

Inserting an object

To insert a new widget, we use the POST verb:

curl -H "Authorization: Espresso MyAPIKey:1" -H "Content-type: application/json" --data-binary "{\"name\": \"My new widget\", \"price\": 199.99}"
-X POST
https://eval.espressologic.com/rest/acme/myproject/v1/widgets

Note the Content-type header: it is required.

The response would be something like:

{
  "statusCode": 201,
  "txsummary": [
    {
      "@metadata": {
        "href": "https://eval.espressologic.com/rest/acme/myproject/v1/widgets/1008",
        "resource": "widgets",
        "verb": "INSERT",
        "checksum": "R:71830068badf0977"
      },
      "ident": 1008,
      "name": "My new widget",
      "price": 199.99
    }
  ]
}

The 201 status code (which is the same as the HTTP response code, but it's nice to also have it in the response) indicates that the insert was successful.

The txsummary object is an array of all the objects that have been modified by this transaction. In this case, it's only the newly inserted object, but if any other objects had been inserted, updated or deleted as a result of logic rules, they would show up in the transaction summary.


Updating an object

If we want to change the price of our newly inserted widget, we can use a PUT and send back the object we received from the insert, with a different price:

curl -H "Authorization: Espresso MyAPIKey:1" -H "Content-type: application/json" --data-binary
"{\"@metadata\": { \"href\": \"https://eval.espressologic.com/rest/acme/myproject/v1/widgets/1008\", \"checksum\": \"R:71830068badf0977\"}, \"price\": 150}"
-X PUT https://eval.espressologic.com/rest/acme/myproject/v1/widgets/1008

The response would be:

{
  "statusCode": 200,
  "txsummary": [
    {
      "@metadata": {
        "href": "https://eval.espressologic.com/rest/acme/myproject/v1/widgets/1008",
        "resource": "widgets",
        "verb": "UPDATE",
        "checksum": "R:a164cfeba97c19db"
      },
      "ident": 1008,
      "name": "My new widget",
      "price": 150
    }
  ]
}

In this case, we assume that no other object was affected by this transaction. The status code of 200 indicates that the update was successful.

Deleting an object

To DELETE this new widget, we can do:

curl -H "Authorization: Espresso MyAPIKey:1" -X DELETE https://eval.espressologic.com/rest/acme/myproject/v1/widgets/1008?checksum=R:a164cfeba97c19db

Here we use the DELETE verb, we provide the primary key of the object (1008) on the URI, and we include the current checksum of the object, which we got from the last update.
Note that you can override the checksum by giving it a value of override, in which case Espresso Logic's optimistic locking will be bypassed, and the object will be deleted regardless of whether someone else has modified it since we last got it. This is usually not what you want, but it's useful when you need it.

The response would be:

{
  "statusCode": 200,
  "txsummary": [
    {
      "@metadata": {
        "href": "https://eval.espressologic.com/rest/acme/myproject/v1/widgets/1008",
        "resource": "widgets",
        "verb": "DELETE"
      },
      "name": "My new widget",
      "price": 150
    }
  ]
}

Once again, the transaction summary could contain other objects affected by this transaction.