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

RESTful Web Service Examples 6

 

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

 

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:

 

 

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 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:

 

 

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

Outgoing Response

A RESTful Web Service can consist of the following:

 

 

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 Body1

Parameter Type2

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.

 

 1 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.

 

 2 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.

 

RESTful Web Service Examples

 

Click here to view a tutorial that shows you how to create a new RESTful Web service and add 3 simple RESTful Web Service endpoints:

 

  1. Retrieve all pets from a pet store. This tutorial demonstrates how to implement a HTTP GET endpoint.
  2. Add a new pet to a pet store. This tutorial demonstrates how to implement a HTTP POST endpoint with Basic Authentication.
  3. Delete a pet from a pet store. This tutorial demonstrates how to implement a HTTP DELETE endpoint with Basic Authentication.

 

Click here for more information regarding implementing RESTful Security.