This tutorial explains how to use the API in a hands-on way. You can use any REST client you like. Here we'll use trusty old curl along with jsonlint for formatting purposes.

We assume that you've already set everything up, including the sample data. The examples below are not exactly from the sample data (it's a TODO for me to update them), but it should be easy enough to figure out how to apply them to the sample data, or to real data if you're using that.


Get items

The first thing we want to do is grab some data out of the API. Since services are the main item type, let's get the list of services. Here's how:

$ curl -H "Accept: application/json" \
> https://seiso.example.com/v1/services \
> | jsonlint

Note that we used the Accept: application/json request header to tell the API that we want a JSON response. The API supports only JSON output; see this FAQ for more information.

The result looks like this:

[
  {
    "_self": "https://seiso.example.com/v1/services/seiso-db",
    "description": "Database for configuration management data",
    "group": {
      "_self": "https://seiso.example.com/v1/service-groups/devops",
      "key": "devops",
      "name": "Devops"
    },
    "key": "seiso-db",
    "name": "Seiso Database",
    "owner": ... ,
    "platform": "MySQL 5.6.17",
    "scmRepository": null,
    "type": {
      "_self": "https://seiso.example.com/v1/service-types/database",
      "key": "database",
      "name": "Database"
    }
  },

  ...
]

If we want to get a single service, then we can do that by appending the service's unique key to the URI as follows:

$ curl -H "Accept: application/json" \
> https://seiso.example.com/v1/services/seiso-db \
> | jsonlint

This time the result is a single service:

{
  "_self": "https://seiso.example.com/v1/services/seiso-db",
  "description": "Database for configuration management data",
  "group": {
    "_self": "https://seiso.example.com/v1/service-groups/devops",
    "key": "devops",
    "name": "Devops"
  },
  "key": "seiso-db",
  "name": "Seiso Database",
  "owner": ... ,
  "platform": "MySQL 5.6.17",
  "scmRepository": null,
  "type": {
    "_self": "https://seiso.example.com/v1/service-types/database",
    "key": "database",
    "name": "Database"
  }
}

Now let's see how to create a new service.


Create items

In general the API uses HTTP PUT for both creating new items and updating existing items. The reason is that the item URIs use meaningful keys as opposed to using arbitrary database identifiers. For example, a person URI looks like this:

https://seiso.example.com/v1/people/wwheeler

and not like this:

https://seiso.example.com/v1/people/14

Because we know the item URI in advance of creating it, we use PUT.

To create a new service with curl, we begin by putting the JSON data in a JSON file, which for the sake of example we'll call super-search-engine.json:

{
  "key": "super-search-engine",
  "name": "Super Search Engine",
  "description": "A wonderful new search engine",
  "group": {
    "_self": "https://seiso.example.com/v1/service-groups/devops",
    "key": "devops" TEMPORARY
  },
  "type": {
    "_self": "https://seiso.example.com/v1/service-types/application",
    "key": "application" TEMPORARY
  }
}

There are a few points worth highlighting here.

  • For the top-level object (i.e., the service that we're creating), we didn't provide a _self property. It's not needed because we're going to make a PUT request to the URI in question.
  • In this example we've omitted a number of properties, such as owner and scmRepository. The API will treat omitted properties as having null values.
  • When specifying properties whose values are objects in their own right, like group and type, we provide a reference to the object, as opposed to providing the entire object. We do this by specifying the object's _self link.

Regarding the TEMPORARY labels: in the current implementation we build references by specifying keys rather than by providing the _self link. This may change depending on this.

Now that we have super-search-engine.json, we can issue a curl command to create the service:

$ curl -X PUT \
> -H "Content-Type: application/json" \
> -d @super-search-engine.json \
> https://seiso.example.com/v1/services/super-search-engine

This type we used Content-Type: application/json to tell the API that we're submitting JSON. Assuming that the object is in fact new, the result will be HTTP 201 Created.

Though we didn't indicate it above, currently PUT requests require basic authentication. If you're using the sample data, you can use username seiso-user and password seiso. We're still working through our approach to authentication and authorization, and we'll update the documentation as we have more information.


Update items

Updating items is pretty much the same as creating them: you just do a PUT request to the relevant URI and pass the JSON data in the payload. The API returns HTTP 204 No Content when the request is successful.

Note that REST semantics dictate that PUT completely replaces whatever was already there.

Try changing the description in the JSON:

{
  "key": "super-search-engine",
  "name": "Super Search Engine",
  "description": "A search engine that we like to think of as Google on steroids",
  "group": {
    "_self": "https://seiso.example.com/v1/service-groups/devops",
    "key": "devops" TEMPORARY
  },
  "type": {
    "_self": "https://seiso.example.com/v1/service-types/application",
    "key": "application" TEMPORARY
  }
}

Then just curl it in:

$ curl -X PUT \
> -H "Content-Type: application/json" \
> -d @super-search-engine.json \
> https://seiso.example.com/v1/services/super-search-engine</pre>

Finally GET the updated item:

$ curl -H "Accept: application/json" \
> https://seiso.example.com/v1/services/seiso-db \
> | jsonlint</pre>

You should see the updated description.


Delete items

Alas, leadership cut funding to our Google competitor, and so it's time to delete Super Search Engine. It's exactly what you would expect:

$ curl -X DELETE https://seiso.example.com/v1/services/super-search-engine

That's it for our tutorial. See the Seiso v1 API Reference for more detailed information on using the API.