Publishing RESTful Web Services Overview
Publishing Web Service Documentation
Getting Started with RESTful Server
See also: RESTful Services, Endpoint Scripting, Server Admin Web Service Administration, Publishing Web Service Documentation, RESTful Web Service Tutorials
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.
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
The incoming HTTP request can contain the following attributes:
The above request attributes can be accessed while processing the endpoint event.
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.
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:
|
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.
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.
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.
This section gives a brief outline of the steps to create a RESTful Web Service.
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.
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. |
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 to view a tutorial that shows you how to create a new RESTful Web service and add 3 simple RESTful Web Service endpoints:
Click here for more information regarding implementing RESTful Security.