cURL Example

cURL is a popular command-line utility to interact with various network protocols, including HTTP and HTTPS. It is pre-installed on the mac, you must install it on Windows.

You can use curl to interact with a REST API, such as API Server. The following are a few examples of using cURL.

Log In

Logging in acquires an the auth token, or API key. Send your credentials to the server by issuing the following command:
curl -d '{"username":"demo","password":"Password1"}' -H "Content-type: application/json" -X POST https://server.acme.com/rest/default/demo/v1/@authentication
The following response is expected:

{
  "apikey": "5b35864f4724ea3e1278c3cd4dc06087",
  "expiration": "2015-11-06T01:26:06.826Z",
  "lastLoginTs": "2015-11-05T01:24:52.943Z",
  "lastLoginIP": "123.45.67.89",
  "email": "jdoe@acme.com"
}

The apikey value is the value the following examples use for APIKEY.

Retrieve Some Data

The following request includes an HTTP header named Authorization that identifies and authenticates the call.
  • APIKEY is the auth token you need to make any calls. You can create your own API keys and give them whatever permissions you require.
  • https://server.acme.com/rest is the base URI. This will depend on how you access CA Live API Creator.
  • acme is the name of your account.
  • myproject is the name of your API project.
  • v1 is the API version you want to access.
  • widgets is the name of your resource, which could be a table or a resource defined for one or more table.
curl -H "Authorization: CALiveAPICreator APIKEY:1" https://server.acme.com/rest/acme/myproject/v1/widgets

The following response assumes there is only one widget in the database, or at least that can be read by this auth token. The following response is expected:

[
 {
    "@metadata": {
      "href": "https://server.acme.com/rest/acme/myproject/v1/widgets/1002",
      "checksum": "R:2b26c827f961d5db"
    },
    "ident": 1002,
    "name": "Demo widget",
    "price": 123.45
  }
]
The @metadata object contains all the information Live API Creator requires for context. You will normally send it as part of the object when interacting with the API.

Filter and Sort

GET provides filter and sort. URL-encode special characters:
# Filter: name like '%Hammer%'
curl -H "Authorization: CALiveAPICreator APIKEY:1" https://server.acme.com/rest/acme/myproject/v1/widgets?filter=name%20like%20%27%Hammer%%27

# Sort: name desc
curl -H "Authorization: CALiveAPICreator APIKEY:1" https://server.acme.com/rest/acme/myproject/v1/widgets?order=name%20desc

This type of "free-form" filter and order may not be allowed in your project. If that is the case, use structured filters and sorts.

Insert an Object

To insert a new widget, use the POST verb:

curl -H "Authorization: CALiveAPICreator APIKEY:1" -H "Content-type: application/json" -d '{"name": "My new widget", "price": 199.99}' 
-X POST
https://server.acme.com/rest/acme/myproject/v1/widgets

The Content-type header is required. The data (-d) is quoted with a single quote, allowing the use of double quotes in the JSON (the JSON standard requires this format).

The following response is expected:
{
  "statusCode": 201,
  "txsummary": [
    {
      "@metadata": {
        "href": "https://server.acme.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 is 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.

Update an Object

You can change the price of the newly inserted widget using the PUT verb and send back the object you received from the insert, with a different price:
curl -H "Authorization: CALiveAPICreator APIKEY:1" -H "Content-type: application/json" -d
'{"@metadata": { "href": "https://server.acme.com/rest/acme/myproject/v1/widgets/1008", "checksum": "R:71830068badf0977"}, "price": 150}' 
-X PUT https://server.acme.com/rest/acme/myproject/v1/widgets/1008

The following response is expected:
{
  "statusCode": 200,
  "txsummary": [
    {
      "@metadata": {
        "href": "https://server.acme.com/rest/acme/myproject/v1/widgets/1008",
        "resource": "widgets",
        "verb": "UPDATE",
        "checksum": "R:a164cfeba97c19db"
      },
      "ident": 1008,
      "name": "My new widget",
      "price": 150
    }
  ]
}
This response assumes that no other object was affected by this transaction. The status code of 200 indicates that the update was successful.

Delete an Object

This example uses the DELETE verb, the primary key of the object (1008) on the URI, and the current checksum of the object, which we got from the update example. You can override the checksum, bypass Live API Creator's optimistic locking, and delete the object regardless of whether someone else has modified it since we last got it by giving it a value of override.
curl -H "Authorization: CALiveAPICreator APIKEY:1" -X DELETE https://server.acme.com/rest/acme/myproject/v1/widgets/1008?checksum=R:a164cfeba97c19db


The following response is expected:
{
  "statusCode": 200,
  "txsummary": [
    {
      "@metadata": {
        "href": "https://server.acme.com/rest/acme/myproject/v1/widgets/1008",
        "resource": "widgets",
        "verb": "DELETE"
      },
      "name": "My new widget",
      "price": 150
    }
  ]
}
The transaction summary can contain other objects affected by this transaction.
Comments