Skip to end of metadata
Go to start of metadata

Crosslight RestClient provides a simple way to perform data access to any REST-compatible service. It takes a RestRequest and process it to an appropriate HTTP request that can be accepted by the target REST service. Upon response, it will parse the HTTP response to a RestResponse instance that typically carry JSON data that you can consume in your apps.

Crosslight implements RestClient in the Core (Portable) layer which means you can consume the RestClient class directly in your shared application project. The platform-specific view automatically display data which is bound to the ViewModel in your shared application. For more information about MVVM and data binding, see Understanding MVVM Pattern in Crosslight.

This page discusses the basic usage and common data access scenarios using RestClient. 

On this page:

Basic Usage

To create a request to a REST service using RestClient, you will need to the followings:

  • Create the RestClient with base url.
    The base url serve as base url for other RestRequest that executed through the RestClient instance. 
  • Create the RestRequest that complies with the target REST API.
  • Execute the request.

The example generates the following HTTP Request.

HTTP Request

GET http://localhost:27040/api/values HTTP/1.1
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
Host: localhost:27040
Connection: Keep-Alive

Adding Parameter(s)

If needed you can add additional parameters using AddParameter method as follows.

The example generates the following HTTP Request.

HTTP Request

GET http://localhost:27040/api/values?param1=value1&param2=1 HTTP/1.1
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
Host: localhost:27040
Connection: Keep-Alive

Adding Body

If preferred you can add the parameter in request body using AddBody method as follows.

The example generates the following HTTP Request.

HTTP Request

POST http://localhost:27040/api/values HTTP/1.1
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
Content-Type: application/json
Host: localhost:27040
Content-Length: 8
Expect: 100-continue
Connection: Keep-Alive

"value1"

 

Furthermore if you have complex data structure that you need to send, it is advisable to store it in request body as follows.

The example generates the following HTTP Request.

HTTP Request

POST http://localhost:27040/api/values HTTP/1.1
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
Content-Type: application/json
Host: localhost:27040
Content-Length: 112
Expect: 100-continue
Connection: Keep-Alive

{"Person":{"FirstName":"Andry Handoko","LastName":"Soesilo"},"Address":{"Country":"Indonesia","City":"Jakarta"}}

 

If the REST service support XML data format you can change the RequestFormat to RequestDataFormat.Xml to comply with it.

The example generates the following HTTP Request.

HTTP Request

POST http://localhost:27040/api/values HTTP/1.1
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
Content-Type: text/xml
Host: localhost:27040
Content-Length: 217
Expect: 100-continue
Connection: Keep-Alive

<ComplexData>
<Person>
<FirstName>Andry Handoko</FirstName>
<LastName>Soesilo</LastName>
</Person>
<Address>
<Country>Indonesia</Country>
<City>Jakarta</City>
</Address>
</ComplexData>

Adding Header

HTTP has several predefined header fields that define the operating parameters of a HTTP transaction. These header fields are not embedded to RestRequest as you can see from the above samples. If needed you can add these header using AddHeader method. You can also add custom header if needed.

The example generates the following HTTP Request.

HTTP Request

GET http://localhost:27040/api/values HTTP/1.1
Accept-Language: en-US
CustomHeader: CustomHeaderValue
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
Host: localhost:27040
Connection: Keep-Alive

Adding Url Segment

Some REST api available also incorporates url segments in their definition to handle specific process such as DELETE, UPDATE, etc.

Example: 

  • DELETE api/customer/ALFKI
  • DELETE api/values/1

To add url segments in your request, you can use AddUrlSegment. Note that the AddUrlSegment requires key pair value, where the key name is basically pointing to {key} placeholder in your RestRequest.

The example generates the following HTTP Request.

HTTP Request

DELETE http://localhost:27040/api/values/1 HTTP/1.1
Accept: application/json, application/xml, text/json, text/x-json, text/javascript, text/xml
Host: localhost:27040
Connection: Keep-Alive

Adding File

Often times, you will find scenarios where the application is required to update an entity which has an image or other files attached to it. To handle the save process in one request, you can use RestClient capability to embed file in RestRequest as follows.