What can you actually do with the Foreman REST API?

Too much to fit into just one article. For now, let’s limit ourselves to creating, editing and reading out data. Foreman is an open source tool that can be used to manage physical or virtual servers. Administrators can control, set up and update all machines registered on Foreman. Once the Foreman has been freshly installed, there are countless setting options to adapt it to your individual needs. For example, environments, architectures, organizations and the locations that you need for your own infrastructure can be created. Once the configuration has been created, you can start working or testing.

To save yourself some work here, you can connect to the Foreman REST API and then import the data there using a script you have created yourself. All defined settings can be compiled in a YAML file, for example, in order to automate the import or creation of new data. REST stands for: Representational state transfer and is executed via HTTP or HTTPS. The REST methods describe the type and manner of data connection for reading, updating, creating or deleting data. API stands for: application programming interface. The API of an application contains defined URLs for executable functions, such as reading configuration settings or creating new data. When using the REST API, calls are made from web addresses with one or more corresponding parameters. If the call and the parameters are valid, the requested information or a status is returned from the target server. For example, all environments created in the Foreman can be read via the following call (GET request):

https://mein-foreman-server.de/api/environments

The information from the Foreman Server about the environments is then output in JSON format:

{
  "total": 34,
  "subtotal": 34,
  "page": 1,
  "per_page": 20,
  "search": null,
  "sort": {
    "by": null,
    "order": null
  },
  "results": [{"created_at":"2015-10-07T07:21:42Z","updated_at":"2015-10-07T07:21:42Z","name":"api_new","id":3},{"created_at":"2015-10-07T07:21:17Z","updated_at":"2015-10-07T07:21:17Z","name":"apitest","id":2}, ...]
}

As you can see, reading information using the REST API is quite easy.

It becomes more difficult with more complex tasks in connection with existing data that is dependent. For example, if you want to import multiple data for organizations or locations that have already been created in Foreman. In this case you have to generate an import with a bit more effort. This is where the following REST API options come into play in order to be able to carry out the import or adjustments automatically.

  • With the bash shell using the CURL command
  • With the Foreman API Gem
  • directly with a programming language

The REST API accesses Foreman 1.9. we tested as follows.

  1. Using CURL via the Bash console
  2. With Ruby versions 1.8.7, 1.9.2 and 2.2.0 and the net/http(s) and uri libraries
  3. With Ruby On Rails 4 and the ActiveResource gem

Our conclusion from the tests with the Forman REST API.

If you plan to briefly test the REST API or make a few minor adjustments using a script, using CURL is probably the easiest and fastest option.

The example above implemented with CURL looks like this.

$ curl -u admin:password -H "Accept:application/json" https://mein-foreman-server.de/api/environments

If you want to perform more complex imports, updates or other cleanups, the use of a programming language is highly recommended. In our examples, we were able to work well with Ruby and the Gem ActiveResource and quickly create an easily understandable and reusable interface.

However, if it is not possible to use the Gem ActiveResource or install it on a server, you can also use the Ruby version available on the server to quickly create a program/script that performs the desired tasks. Alternatively, there is also a gem from the Foreman developers called Foreman API.

What can you actually do with the Foreman REST API? – Quite a lot!

+ posts