Microsoft C++ REST SDK

Microsoft C++ REST SDK version 1.0 codename Casablanca is open source project hosted at GitHub, and takes advantage of the new set of capabilities introduced in C++ 11 to simplify cloud-based coding with a modern, asynchronous, and multi-platform API design.

The C++ REST SDK is included with Visual Studio 2013, and is also released as a separate project on github. The github project is updated independently of Visual Studio and might contain updates and features that are not included with Visual Studio. You can install the Visual Studio and github releases side-by-side on the same computer.

The C++ REST SDK is supported on both Visual Studio 2015 and 2017. It provides powerful models to writing asynchronous code based on new C++ 11 features. REST services from any native code written on multiple operating systems can be accessed through C++ SDK.

Here are some of the features of C++ REST SDK:

Programming with Tasks

All the asynchronous APIs in Casablanca are build on the PPL tasks library available as part of Visual Studio 2015. There is also a special version of PPL tasks library available for VS 2010 and Linux.

Platform Independent Strings

Preferred representation of textual data in the form of strings is different depending on the platform. So, in order to write platform independent code, C++ REST SDK defines typedef utility::string_t which corresponds to platform preference.

HTTP Client

In C++ SDK, HTTP client class is used to maintain connection to an HTTP service i.e. web::http::client::http_client. The constructor accepts a string or URI to make the connection with service i.e.

web::http::client::http_client client(U("http://localhost:1234"));

Next is to call request method to make the request i.e.

client.request(web::http::methods::GET, U("index.html"));

HTTP Listener

HTTP listener is a C++ object that accepts messages directed at a particular URI. HTTP listeners APIs can be found in the class web::http::experimental::listener. Creating a listener object is same as client i.e.

http_listener listener(L"http://localhost/path");

Asynchronous Streams and Stream Buffers

The concrete implementations of streams buffers are Producer Consumer, File Streams, Container Streams, Raw Pointer Streams, Interop Streams.

JSON

In C++ REST SDK all JSON values are represented by the web::json::value class; it doesn’t matter whether it’s a number, a string, or an object, from a static type perspective.

There’s a value factory function for each of the six types of JSON values. In addition, there are overloads of the functions to create string, object, and array values. Here are some examples of constructing JSON values:

using namespace web;
json::value v0 = json::value::null();
json::value v1 = json::value::number(20);
json::value v2 = json::value::number(4.5);
json::value v3 = json::value::boolean(true);
json::value v4 = json::value::string(U("String Literal"));
json::value v5 = json::value::object();
json::value v6 = json::value::array();

Uniform Resource Identifier (URI)

Uniform resource identifiers (URIs) are, as you probably already know, structured strings that are used to specifically identify various entities in the world. URIs used with HTTP have the following format:

protocol : // server [: port] / path ? query # fragment

The main class is web::http::uri, which represents a fully formed identifier. There is also a web::http::uri_builder class which can be used to incrementally build the URI such as

web::http::uri_builder builder;
web::http::uri_builder builder(U("http://localhost:80/"));
builder.set_path(U("user/details"));
builder.set_query(U("userid=123"));
builder.set_fragment(U("last"));

Linux Features

Almost all of the features listed above are supported on Linux as well i.e. Asynchronous Stream, JSON, URI and URIBuilder andHTTP Client.

Sample Program to connect to an HTTP Server with C++ REST SDK

// Creates an HTTP request and prints the length of the response stream.
pplx::task<void> HTTPStreamingAsync()
{
    http_client client(L"http://www.fourthcoffee.com");
    // Make the request and asynchronously process the response.
    return client.request(methods::GET).then([](http_response response)
    {
        // Print the status code.
        std::wostringstream ss;
        ss << L"Server returned returned status code " << response.status_code() << L'.' << std::endl;
        std::wcout << ss.str();
       // TODO: Perform actions here reading from the response stream.
        auto bodyStream = response.body();
        // In this example, we print the length of the response to the console.
        ss.str(std::wstring());
        ss << L"Content length is " << response.headers().content_length() << L" bytes." << std::endl;
        std::wcout << ss.str();
    });

    /* Sample output:
    Server returned returned status code 200.
    Content length is 63803 bytes.
    */}