HTTP REST framework in C for embedded systems

Based on libmicrohttpd, jansson and libcurl, this framework allows to simply create web applications and manipulate http requests, with json format if needed.

With this framework, you simply initialise the instance and its endpoints.

For each endpoint, you provide a callback function that will be called each time the endpoint is reached by a client.

In the callback function, you have access to a request structure, a response structure you can modify, and a user-defined pointer for a database connection for example.

Using this framework makes it easy to create small applications that will quickly access the GPIO of your RPi for example, system functions or network resources, and be controllable via a web interface. All this with a small memory consumption (a few MB).

Short API description

To start, you need to declare a struct _u_instance and initialize it, this structure will contain the instance parameters, like the port number and the endpoints.

  struct _u_instance instance;
  if (ulfius_init_instance(&instance, PORT, NULL) != U_OK) {
    fprintf(stderr, "Error ulfius_init_instance, abort");
    return(1);
  }

After you stop the webserver framework, don't forget to clean the instance structure if you don't need it anymore, using ulfius_clean_instance.

You'll need to add endpoints to your instance. An endpoint contains an url pattern and a callback function pointer. The url can contain variables, for example:

/test/first
/test/second
/testWithParams/@param1/@param2

To add an endpoint, use for example the following function:

int ulfius_add_endpoint_by_val(struct _u_instance * u_instance,
                               const char * http_method,
                               const char * url_prefix,
                               const char * url_format,
                               int (* callback_function)(const struct _u_request * request,
                                                         struct _u_response * response,
                                                         void * user_data),
                               void * user_data);

To start and stop the framework, use the following functions:

int ulfius_start_framework(struct _u_instance * u_instance);
int ulfius_stop_framework(struct _u_instance * u_instance);

The function ulfius_start_framework will start the webservice in a separate thread.

You can add or remove endpoints during the framework execution, the configuration will be automatically updated.

Each time an endpoint is called by a client, the callback function is executed with the connection parameters. A callback function has the following signature:

  int (* callback_function) (const struct _u_request * request,
                            struct _u_response * response,
                            void * user_data);

In your callback function, you can process the request parameters and build the response. The framework will send back your response to the client.

The callback function is where your code happens, as this sample hello world callback function:

int callback_hello_world (const struct _u_request * request, struct _u_response * response, void * user_data) {
  response->string_body = strdup("Hello World!");
  response->status = 200;
  return U_OK;
}

You can also use json objects provided by the jansson library in your callback function with the elements struct _u_request.json_body and struct _u_response.json_body which are json_t * pointers.

You can read a more complete documentation in the github project README.md file.