Web Services REST (REpresentational State Transfer)

Information about REST

Representational State Transfer (REST) is a style of software architecture for distributed systems such as the World Wide Web. REST has emerged as a predominant web API design model.

The REST architectural style was developed by W3C Technical Architecture Group (TAG) in parallel with HTTP/1.1, based on the existing design of HTTP/1.0.[5] The World Wide Web represents the largest implementation of a system conforming to the REST architectural style.

REST-style architectures conventionally consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.

REST is an architecture style for designing networked applications. The idea is that, rather than using complex mechanisms such as CORBA, RPC or SOAP to connect between machines, simple HTTP is used to make calls between machines.

RESTful applications use HTTP requests to post data (create and/or update), read data (e.g. make queries), and delete data. Thus REST uses HTTP for all four CRUD (Create/Read/Update/Delete) operations.

See Wikipedia for more information.

How it works

The client makes a http request to the server using a URL and a http method (GET, POST, PUT or DELETE). We may say that the URL specifies the server resource. For example we can refer to an employee with http://whateverdomain/employees?id=25

In this case we refer to user with ID number 25. Then we must use one of the http methods:

  • GET: Used to read the resource (may return the employee with ID 25 information).

  • POST: Can be used to insert or perhaps modify the remote resource (parameters can be sent via URL parameters or as form post parameters in the message body).

  • DELETE: To delete the resource (in this case the one with the ID 25).

  • PUT: To modify (or create) a remote resource.

  • HEAD: Like a GET but return only the headers.

  • OPTIONS: What methods are allowed for this resource.

Depending on what is implemented on the server, one behaviour or another may be provided. As there is no standard, it must be well specified and explained on the Web service Help or Web Service interface definition.

The client request may contain information in the message “body” (for the POST method). This information is normally stored using an XML or JSON syntax (lately JSON is the preferred way as it’s smaller in size).

The server receives the URL identifying some resource served by the Web Service and the method. From this information the server may trigger whatever logic it has to execute to achieve the required results (for example read some data files to extract the employee information) and return a response to the client.

The server response comprises mainly two parts, the http status (200 -> OK, 404…) and the message body (which again may be in XML or JSON). In the previous example, if successfull it will return status OK (200) and in JSON the response body with the employee information.

How we can use REST with Sculptor

This development has three different parts:

  1. XML and JSON parsing

    Sculptor programs behaving as client or server need to translate the XML or JSON stream into a manageable structure inside the Sculptor program, so this XML and JSON parsing will translate the stream into sculptor data and populate a !record or ![o]file structure where the field names must be the same names as the fields in the XML or JSON stream. Using the functions for reading/writing JSON/XML and the nph-srep JSON/XML functions.

    Since Sculptor version 6.2.0 the nested record and record array features make possible that all the different XML or JSON streams can be represented.

  2. Client

    The client is just a simple http client which issues a GET, POST, PUT, DELETE, HEAD or OPTIONS method (defined in www.h header) over a URL. In some cases a record information may be converted to JSON or XML and sent with the request. In other cases a buffer is send as received (binary or ASCII field).

    The response from the server will be divided into two parts, the status and the content, which again may be an XML or JSON stream transformed into a record or if a ASCII or binary field is received the raw response will be returned.

    To send a request to an HTTP server and wait for the response the http_simple_send() function can be used.

  3. Server

    The Server will be based on nph-srep as it is just a http server. We added some extra functionality to make it easier to implement a REST server service, like:

    • get_web_method() can be used on nph-srep to check the http methods (GET, POST…)

    • getenv(“CONTENT_TYPE”) can be used to know the received content type (application/json, application/xml,…)

    • read_web_json_values() and read_web_xml_values() read the received JSON/XML content into a !record

    • An XML response back to the client would be something similar to:

      web_content_type("application/xml")
print_xml(response, JSONXML_MINIFY)

    • A JSON response back to the client would be something similar to:

      web_content_type("application/json")
print_json(response, JSONXML_MINIFY)

    • Two new Sculptor template Files have been added to return JSON (*.scj) and XML (*.scx) content (Setting the retuned content type automatically).

Where and when this can be used

With the advent of the new mobile platform paradigm, the use of Web Services (with REST at the top) has seen a big increase. It can provide those benefits:

  • Reduce CPU execution in the mobile device (moving the business logic to the server).

  • Reduce the data transmission (as all the information is accessed in the server and only the required response is transmitted)

  • Increase the performance by not having the long latency times of the many data transmission.

  • It’s a simple interface and a kind of standard.

  • The client and server may be implemented in different languages (Sculptor, JavaScript, PHP, Java, C# - .Net, C, C++, Ruby, Python,…).

Often, a single client operation involves several queries on the server databases and then updates to some tables and as a result just obtains a few items of information. In this case, the use of a Web Service saves lot of CPU, data bandwidth and time.

There are many “REST” services that can be used for many pourposes: