Publishing RESTful Web Services Overview

Documentation home

Introduction. 1

Documentation links 2

RESTful Server Architecture. 2

Incoming Request 2

Outgoing Response. 2

HTTP Methods 3

Publishing a Web Service. 4

Publishing Web Service Documentation. 5

Getting Started with RESTful Server 5

Error Handling. 5

RESTful Web Service Security. 6

See also: RESTful Services, Endpoint Scripting, Server Admin Web Service Administration, Publishing Web Service Documentation

Introduction

Verj.io provides the ability to publish a REST web service by creating a RESTful Web Service. REST (REpresentation State Transfer) is a flexible lightweight architecture that supports passing and receiving data of all types.

Each RESTFul Web Service can contain any number of endpoints where each endpoint:

• represents an entry URL

• is linked to a Javascript script which is executed when a request is received. A Javascript API provides access to both the received and returned data.

• specifies which operations (verbs) are supported e.g GET, POST, PUT and DELETE

Normally all the endpoints within a service provide related functionality e.g. a customer service might provide endpoints to get, update and delete a customer record.

Information can be passed into a service in a variety of ways including path parameters (i.e. as part of the request URL), request parameters, request headers or as part of the request body. Typically information is returned to the caller as a response body, but response headers and http status codes can also be used to return information. Any text-based mime types e.g. JSON, XML, CSV, SOAP etc can be consumed (received as request body) or produced (returned as response body), although data structures are most commonly transferred as JSON. There are many web frameworks readily available that consume or produce JSON data.

RESTful web services run over HTTP, are stateless, and run in the background. There is no user associated with the execution of each request. Execution of a RESTful web service request is lightweight and is designed to be very efficient at processing request and response data.

Documentation for each service can be published as swagger YAML and JSON documentation.

From a designer’s perspective, a RESTful Web Service is very similar to a form except that it contains no pages. A RESTful Web Service contains a collection of endpoints where each endpoint supports one main event - an Endpoint Event - that is processed immediately when a request for the endpoint is received. An On Error Event can also be configured to execute when an error occurs.

Documentation links

• RESTful Web Service - describes creation and configuration of a RESTful Web Service
• Endpoint Scripting – describes endpoint programming including the Javascript API to access received/returned data
• Publishing Web Service Documentation – describes creation and publishing of documentation for each service/endpoint
• Server Admin Web Service Administration – provides the ability to enable/disable a service and control visibility of the published documentation

RESTful Server Architecture

The Verj.io RESTful Server operates as a servlet that accepts requests via HTTP. The incoming URL is used to locate and execute the ‘Endpoint Event’. The RESTful Web Service is designed to be as lightweight as possible. All of the attributes described below in the Incoming Request and Outgoing Response sections can be accessed directly from the event script using the JavaScript API - see Endpoint Scripting for more information

Incoming Request

The incoming HTTP request can contain the following attributes:

• HTTP Method (GET, POST, etc…) - mandatory
• HTTP Request Headers - optional
• Request body - optional
• Path Parameters - optional
• Query/Post Parameter - optional

The above request attributes can be accessed while processing the endpoint event.

Outgoing Response

A RESTful Web Service can consist of the following:

• HTTP Response Status Code – optional (default is 200)
• HTTP Response headers - optional
• Response Body - optional

The above response attributes can be set while processing the endpoint event.

Each RESTful Web Service can contain one or more endpoints.

HTTP Methods

The supported HTTP/1.1 methods are defined below. Not all the methods support a request or response body. All HTTP methods must return a response code (the default response code is 200) and optionally they can return HTTP response headers. The method names are case sensitive and must be used in uppercase.

Method	Request Body	Response Body^1	Parameter Type^2	Description
GET	No	Yes	URI	The GET request can only be used to retrieve information from the server. It does not accept a request body and should not change any data on the server.
HEAD	No	No	URI	This is the similar to the GET method except there is no response body returned.
POST	Yes	Yes	POST	The POST request is used to send and update information on the server, for example, update an existing customer record.
PUT	Yes	Yes	POST	The PUT request is used to add or update information on the server, for example add a new customer or update an existing customer. If a resource has been created, the HTTP response code 201 should be returned. If the resource has been updated then a HTTP response code of 200 should be returned.
DELETE	No	Yes	URI	The DELETE method is used to remove information from the server. The following HTTP responses should be adhered to: 200 (OK) and return a response body describing the status, for example, {customerId: 100, updated: true}. 202 (Accepted) should be returned if the action has not been enacted. 204 (No Content) if the request has been enacted but the response does not include a response body.

¹ A response body will not be returned if the HTTP status code is set to 204 (No Content) regardless of whether a response body is supported.

² Parameters can be either:

· URI parameters make up part of the URI request. These parameters are appended to the end of the URI and appear after the ? of the URI and are separated by an ampersand (&) e.g http://localhost:3030/ebase/api/customer/get?customerId=200&lang=US

· POST parameters are the same as URI parameters apart from the parameters make up the request body instead of being added to the URI. The receiving request HTTP header Content-Type should contain the value: application/x-www-form-urlencoded.

Publishing a Web Service

A RESTful Web Service is published automatically and no specific action is needed. If required, each published RESTful Web Service can subsequently be disabled or enabled using the Server Administration Application.

Publishing Web Service Documentation

The RESTful Web Service documentation is enabled as default and can be entered at design time. If required, the published documentation can be enabled or disabled using the Server Administration Application.

See publishing RESTful Web Service documentation for more information.

Getting Started with RESTful Server

This section gives a brief outline of the steps to create a RESTful Web Service.

1. Create a new RESTful Web Service. A new service can be created from the designer menu by clicking New > RESTful Web Service
2. Add fields, tables and resources to the RESTful Web service as required.
3. Map fields to resources (if applicable) e.g Database Resource, Email Resource etc…
4. Add a new endpoint by clicking on the button on the toolbar to add a new endpoint in the left hand panel. Give the endpoint name a meaningful name.
5. Select the supported HTTP method, the default is GET.
6. Edit the endpoint URI. This should start with a forward slash and is used to uniquely identify the endpoint.
7. Create an Endpoint Script. Edit the script to add the logic required. Add the script to the ‘Endpoint’ event scripts tab.
8. Test the RESTful Service by clicking the icon on the Endpoint Configuration Panel toolbar.

Error Handling

Errors should be handled in each endpoint script and then returned to the caller using the appropriate HTTP response status and message. Unhandled errors are returned as status code 500 (server error) and the detail error message is returned in the response body.

Internal HTTP Response Status

The default response code returned from the server is 200 (OK), but in the event of an internal error, the following table shows a list of the internal errors that may be returned from the RESTful Server.

Response Status Code	Status Code Description	Error Description
400	BAD REQUEST	The server cannot process the request because the incoming request URI is incorrect
404	NOT FOUND	The server cannot find the RESTful Web Service URI or the requested endpoint in the request URI.
405	METHOD NOT ALLOWED	The requested HTTP method is not supported.
415	UNSUPPORTED MEDIA TYPE	The requested HTTP header Content-Type does not match the RESTful Service consumes configuration.
500	INTERNAL SERVER ERROR	An unexpected error occurred whilst processing the request.

RESTful Web Service Security

The RESTful Web Service does not support any security implementations as default. Typically not all endpoints require authentication. Many RESTful web services do not require authentication on GET methods that return data that is not sensitive information. Authentication can be added to the Endpoint Script when required, this might be when data is modified on the server or sensitive information is returned from the server.

Click here for more information.

Click here for more information regarding implementing RESTful Security.