{"id":1723,"date":"2013-02-26T12:32:00","date_gmt":"2013-02-26T12:32:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/vcblog\/2013\/02\/26\/the-c-rest-sdk-casablanca\/"},"modified":"2019-02-18T18:41:14","modified_gmt":"2019-02-18T18:41:14","slug":"the-c-rest-sdk-casablanca","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/the-c-rest-sdk-casablanca\/","title":{"rendered":"The C++ REST SDK (&#034;Casablanca&#034;)"},"content":{"rendered":"<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">The C++ REST SDK (codename &#8220;Casablanca&#8221;) has officially been released as an open source project on CodePlex (<a href=\"http:\/\/casablanca.codeplex.com\">http:\/\/casablanca.codeplex.com<\/a>). <\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">We first <a href=\"http:\/\/blogs.msdn.com\/b\/vcblog\/archive\/2012\/04\/30\/10299181.aspx\"> announced<\/a> Casablanca as an incubation project on Microsoft&#8217;s DevLabs back in April of 2012. Since then we have had several releases and have seen library quickly evolve. As we added new features and received feedback from customers, it was evident that two separate entities were beginning to form. As a result, the &#8220;Casablanca&#8221; project on DevLabs has been separated into 2 different SDKs: the<em> C++ REST SDK<\/em> and the<em> Azure SDK for C++<\/em>. <\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">&nbsp;The first of the two SDKs being released is the C++ REST SDK. It includes tools to quickly write modern, asynchronous C++ code that connects with REST services. We take advantage of the power and productivity offered in C++11 while providing a cross-platform solution. We currently support Windows 7, Windows 8 (Windows store and desktop applications), and Linux. <\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">&nbsp;The main features in this SDK include:<\/span><\/p>\n<ul>\n<li><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Ability to create a connection to a server via a HTTP Client, send requests and handle response.<\/span><\/li>\n<li><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Support for construction and use of Uniform Resource Identifiers (URI).<\/span><\/li>\n<li><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Constructing, parsing and serializing JSON values.<\/span><\/li>\n<li><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Asynchronously reading\/writing bytes to\/from an underlying medium via Streams and Stream Buffers.<\/span><\/li>\n<\/ul>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Let&#8217;s look at some code to get a glimpse of the aforementioned features in action. <\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">This first example is a simple application that uploads a file to an HTTP Server.&nbsp; <\/span><\/p>\n<table class=\"style1\" style=\"width: 100%\">\n<tbody>\n<tr>\n<td>\n<p><span style=\"font-size: small\"><span style=\"color: #0000ff;font-family: Consolas\"> #include<\/span> <span style=\"color: #a31515;font-family: Consolas\">&lt;http_client.h&gt; <\/span> <\/span><br \/><span style=\"font-size: small\"> <span style=\"color: #0000ff;font-family: Consolas\">#include<\/span><span style=\"color: #a31515;font-family: Consolas\">&lt;filestream.h&gt;<\/span> <\/span><br \/><span style=\"font-size: small\"> <span style=\"color: #0000ff;font-family: Consolas\"> #include<\/span> <span style=\"color: #a31515;font-family: Consolas\">&lt;uri.h&gt;<\/p>\n<p> <span style=\"color: #0000ff;font-family: Consolas\"> using<\/span> <span style=\"color: #0000ff;font-family: Consolas\">namespace<\/span><span style=\"color: black;font-family: Consolas\"> concurrency::streams;<br \/> <\/span><span style=\"color: #0000ff;font-family: Consolas\"> using<\/span> <span style=\"color: #0000ff;font-family: Consolas\">namespace<\/span><span style=\"color: black;font-family: Consolas\"> web::http::client;<br \/> <\/span><span style=\"color: #0000ff;font-family: Consolas\"> using<\/span> <span style=\"color: #0000ff;font-family: Consolas\">namespace<\/span><span style=\"color: black;font-family: Consolas\"> web::http;<\/p>\n<p><span style=\"color: #0000ff;font-family: Consolas\">int<\/span><span style=\"font-family: Consolas\"> main()<br \/> {<br \/> <\/span><span style=\"color: #008000;font-family: Consolas\">&nbsp; \/\/ Open stream to file.<br \/> <\/span><span style=\"font-family: Consolas\">&nbsp; file_stream&lt;<\/span><span style=\"color: #0000ff;font-family: Consolas\">unsigned&nbsp;<\/span><span style=\"color: #0000ff;font-family: Consolas\">char<\/span><span style=\"font-family: Consolas\">&gt;::open_istream(L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;myfile.txt&#8221;<\/span><span style=\"font-family: Consolas\">).then([](basic_istream&lt;<\/span><span style=\"color: #0000ff;font-family: Consolas\">unsigned&nbsp;<\/span><span style=\"color: #0000ff;font-family: Consolas\">char<\/span><span style=\"font-family: Consolas\">&gt; fileStream)<br \/> &nbsp; {<br \/> <\/span><span style=\"color: #008000;font-family: Consolas\">&nbsp;&nbsp;&nbsp; \/\/ Make HTTP request with the file stream as the body.<br \/> <\/span><span style=\"font-family: Consolas\">&nbsp;&nbsp;&nbsp; http_client client(L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;http:\/\/www.myhttpserver.com&#8221;<\/span><span style=\"font-family: Consolas\">); <br \/> &nbsp;&nbsp;&nbsp; client.request(methods::PUT, L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;myfile&#8221;<\/span><span style=\"font-family: Consolas\">, fileStream).then([fileStream](http_response response)<br \/> &nbsp;&nbsp;&nbsp; {<br \/> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; fileStream.close();<br \/> <\/span><span style=\"color: #008000;font-family: Consolas\">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; \/\/ Perform actions here to inspect the HTTP response&#8230;<br \/> <\/span><span style=\"color: #0000ff;font-family: Consolas\">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if<\/span><span style=\"font-family: Consolas\">(response.status_code() == status_codes::OK)<br \/> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {<br \/> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }<br \/> &nbsp;&nbsp;&nbsp; });<br \/> &nbsp; });<\/span><\/span><\/span><\/span><\/p>\n<p><span style=\"font-size: small\"><span style=\"color: #a31515;font-family: Consolas\"><span style=\"color: black;font-family: Consolas\"><span style=\"font-family: Consolas\">&nbsp;&nbsp;<span><span style=\"color: #0000ff\">return<\/span> 0;<\/span><br \/> }<\/span><\/span><\/span><\/span><\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">We use the <\/span><span style=\"font-size: 10.0pt;font-family: Consolas;color: black\"> concurrency::streams::file_stream<\/span><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\"> class to asynchronously read a file from disk. The constructor of the file stream returns a PPL task of a <\/span> <span style=\"font-size: 10.0pt;font-family: Consolas;color: black\">basic_istream. <\/span><\/p>\n<p><span style=\"color: black;font-family: 'Calibri','sans-serif';font-size: 11pt\">Within the continuation we create an instance of <\/span> <span style=\"color: black;font-family: Consolas;font-size: 10pt\">http_client<\/span><span style=\"color: black;font-family: 'Calibri','sans-serif';font-size: 11pt\"> to represent the connection to the server. Using this instance we can now send requests. In this example we use the <\/span> <span style=\"color: black;font-family: Consolas;font-size: 10pt\"> web::http::methods::PUT<\/span><span style=\"color: black;font-family: 'Calibri','sans-serif';font-size: 11pt\"> to specify the operation as an HTTP PUT request. We also include the name of the file and the file stream in our request. <span style=\"font-family: Consolas;font-size: x-small\"> <span style=\"color: black;font-family: 'Calibri','sans-serif';font-size: 11pt\">Finally, we capture the <span style=\"color: black;font-family: Consolas;font-size: 10pt\">http_response <\/span>in a continuation and perform the necessary actions to inspect if the request was successfully processed by the server. <\/span><\/span><\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">This example illustrates how straight-forward writing a responsive client application that connects to a service can be.<\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Next we will demonstrate how to build a JSON value in memory and loop through its values. <\/span><\/p>\n<table class=\"style1\" style=\"width: 100%\">\n<tbody>\n<tr>\n<td>\n<p><span style=\"font-size: small\"><span style=\"color: #0000ff;font-family: Consolas\">#include <\/span><span style=\"color: #a31515;font-family: Consolas\">&lt;json.h&gt; <\/span><\/span><\/p>\n<p><span style=\"font-size: small\"><span style=\"font-family: Consolas\"><span style=\"color: #0000ff\">int<\/span> main()<br \/> {<br \/> <\/span><span style=\"color: #008000;font-family: Consolas\">&nbsp; \/\/ Create a JSON object.<br \/> <\/span><span style=\"font-family: Consolas\">&nbsp; json::value obj;<br \/> &nbsp; obj[L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;key1&#8221;<\/span><span style=\"font-family: Consolas\">] = json::value::boolean(<\/span><span style=\"color: #0000ff;font-family: Consolas\">false<\/span><span style=\"font-family: Consolas\">);<br \/> &nbsp; obj[L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;key2&#8221;<\/span><span style=\"font-family: Consolas\">] = json::value::number(44);<br \/> &nbsp; obj[L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;key3&#8221;<\/span><span style=\"font-family: Consolas\">] = json::value::number(43.6);<br \/> &nbsp; obj[L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;key4&#8221;<\/span><span style=\"font-family: Consolas\">] = json::value::string(U(<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;str&#8221;<\/span><span style=\"font-family: Consolas\">));<\/p>\n<p> <\/span><span style=\"color: #008000;font-family: Consolas\">&nbsp; \/\/ Loop over each element in the object.<br \/> <\/span><span style=\"color: #0000ff;font-family: Consolas\">&nbsp; for<\/span><span style=\"font-family: Consolas\">(<\/span><span style=\"color: #0000ff;font-family: Consolas\">auto<\/span><span style=\"font-family: Consolas\"> iter = obj.cbegin(); iter != obj.cend(); ++iter)<br \/> &nbsp; {<br \/> <\/span><span style=\"color: #008000;font-family: Consolas\">&nbsp;&nbsp;&nbsp; \/\/ Make sure to get the value as const reference otherwise you will end up copying<br \/> &nbsp;&nbsp;&nbsp; \/\/ the whole JSON value recursively which can be expensive if it is a nested object.<br \/> <\/span><span style=\"color: #0000ff;font-family: Consolas\">&nbsp;&nbsp;&nbsp; const<\/span><span style=\"font-family: Consolas\"> json::value &amp;str = iter-&gt;first;<br \/> <\/span><span style=\"color: #0000ff;font-family: Consolas\">&nbsp;&nbsp;&nbsp; const<\/span><span style=\"font-family: Consolas\"> json::value &amp;v = iter-&gt;second;<\/p>\n<p> <\/span><span style=\"color: #008000;font-family: Consolas\">&nbsp;&nbsp;&nbsp; \/\/ Perform actions here to process each string and value in the JSON object&#8230;<br \/> <\/span><span style=\"font-family: Consolas\">&nbsp;&nbsp;&nbsp; wprintf(L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;String:%s&#8221;<\/span><span style=\"font-family: Consolas\">, str.as_string());<br \/> &nbsp;&nbsp;&nbsp; wprintf(L<\/span><span style=\"color: #a31515;font-family: Consolas\">&#8220;Value:%s&#8221;<\/span><span style=\"font-family: Consolas\">, v.to_string());<br \/> &nbsp; }<br \/><\/span><\/span><span style=\"font-family: Consolas;font-size: small;color: #0000ff\">&nbsp; return<\/span><span style=\"font-family: Consolas;font-size: small\">&nbsp;0;<br \/><\/span><span style=\"font-family: Consolas;font-size: small\">}<\/span><\/p>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">In the C++ REST SDK all JSON values are represented by the <\/span> <span style=\"font-size: 10.0pt;font-family: Consolas;color: black\">web::json::value<\/span><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\"> class. In the example we build our JSON object using the value factory functions. A JSON value can also be parsed from a stream using a constructor that takes a stream reference. Once we have our JSON value we can use the <\/span> <span style=\"font-size: 10.0pt;font-family: Consolas;color: black\">cbegin<\/span><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\"> and <\/span> <span style=\"font-size: 10.0pt;font-family: Consolas;color: black\">cend<\/span><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\"> methods to return read-only iterators for the value collection. <\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Including this simple yet powerful representation of JSON objects in the SDK, provides developers with a set of tools that are productive and compose well together. <\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Thanks for taking the time to read this post, we hope that everyone gets a chance to visit the project on <a href=\"http:\/\/casablanca.codeplex.com\">CodePlex<\/a>, we would love to hear your feedback. <\/span><\/p>\n<p><span style=\"font-size: 11.0pt;font-family: 'Calibri','sans-serif';color: black\">Stay tuned for more updates about both the C++ REST SDK and the Azure SDK for C++. A special thanks to Steve Gates for reviewing this post and providing the code snippets. <\/span><\/p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>The C++ REST SDK (codename &#8220;Casablanca&#8221;) has officially been released as an open source project on CodePlex (http:\/\/casablanca.codeplex.com). We first announced Casablanca as an incubation project on Microsoft&#8217;s DevLabs back in April of 2012. Since then we have had several releases and have seen library quickly evolve. As we added new features and received feedback [&hellip;]<\/p>\n","protected":false},"author":268,"featured_media":35994,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1723","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-cplusplus"],"acf":[],"blog_post_summary":"<p>The C++ REST SDK (codename &#8220;Casablanca&#8221;) has officially been released as an open source project on CodePlex (http:\/\/casablanca.codeplex.com). We first announced Casablanca as an incubation project on Microsoft&#8217;s DevLabs back in April of 2012. Since then we have had several releases and have seen library quickly evolve. As we added new features and received feedback [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/1723","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/268"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=1723"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/1723\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/35994"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=1723"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=1723"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=1723"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}