creating a RESTful web service |
Web Services |
A RESTful Web Service provides access to your application using the standard HTTP protocol. The RESTful Web Service that is defined, calls a PROIV Task through a Structured Data Object (SDO) which holds the details of the service HTTP request. This SDO can be interrogated using PROIV logic.
There are two parts in a RESTful Web Service, the server and the client. PROIV can act as a client or a server but the Restful Service Definition only relates to PROIV as a server.
As a Server, the RESTful Service Definition holds server information that tells PROIV about the details of the protocol that is used (HTTP/HTTPS), any security information required (CORS and Security), the HTTP URL which is used (Connector and Path), the HTTP method which is used (Method) and the PROIV Task to call (Task). When a RESTful Web Service is enabled, PROIV uses this information and creates a server for the RESTful Service.
As a Client, the RESTful Service Definition holds client information for Code Generation feature to produce a library that can be used to call a RESTful Service. The library can be either PHP or Objective-C. The client information in the RESTful Service Definition is the protocol that is used (HTTP/HTTPS), the HTTP URL which is used (Connector and Path), the HTTP method which is used (Method), the request parameters which are required (Parameters and Body), the response codes which are expected (Status Code) and the response data that is expected (Schema).
To create a RESTful Web Service definition:
Open PROIV Control Panel and click Web Services.
Expand RESTful Web Services and click Manage RESTful Web Services.
Click Create.
Configure the RESTful Web Service as follows and click Save.
The service is created on the server.
Item |
Description |
Name |
Enter a unique name that identifies the RESTful Service. |
Description |
Enter any text to describe the service. |
Connector |
Select the required service connector from the list of the connectors defined in the Web Services. In case you have no connectors defined you will not be able to select a connector for the service. See Connector Configuration. |
CORS |
Abbreviation for Cross-Origin Resource Sharing. This is a mechanism that allows a restricted resource on a web page to be requested from another domain outside the domain from which the resource originated. The CORS field also holds the comma separated list of origins that are acceptable to the service. If you want to accept requests with no origin, then the CORS field must be empty (that is, CORS is turned off). The CORS field holds a list of origins and if the field contains at least one origin (* is counted as an origin) then the request must contain an ‘Origin’ header that matches one of the origins in the field. If it does not, then the request will be rejected with an error status (403 – Forbidden). An origin can be either a protocol/host/port triple or a GUID (Globally Unique Identifier). If the origin is triple (most likely) then it can be defined in the CORS field as a full triple, without the protocol or without the port. The host must always be fully defined and no wild cards are allowed in the host name. An origin defined in the CORS field without a protocol will use whatever protocols are defined for the service. The protocol defined for a service always overrides any protocol defined in an origin in the CORS field when looking for a match. For example, an origin of ‘http://myhost.com:80’ will never match if the service does not have the http protocol enabled even if the origin supplied in the request is identical. An origin defined in the CORS field without a port will use the default port defined for the service to do a match. For http that is ‘80’ and for https that is ‘443’. It is acceptable to define an origin in the CORS field with just a host name. In this case it will attempt to match request origins using all the protocols defined for the service and the default port defined for the protocol. |
Enabled |
Select the Enabled check box to turn on the Service. If this is not set then the service is not available. If you set this and save the service it might be auto disabled where a red appears. Click red to view the message dialog that explains why the service has been auto disabled. |
Security id |
Enter the security id. Setting the security id enables HTTP access security on the service. The server sends the text in this field to the client requesting the service and the client needs to respond with the security secret specified in the next field. |
Secret |
Enter the secret text that the HTTP client needs to respond with if there is a security id. If there is no security id then this field is ignored. |
Protocol |
The protocol used for the service can be HTTP, HTTPS or both but you must have at least one protocol selected. |
Max Age |
Enter the number of seconds that a CORS pre-flight request can cache its results before it needs to repeat the pre-flight request. This number is returned in the response header ‘Access-Control-Max-Age’ for a pre-flight request. |
Req Headers |
Enter the request header name for the service to accept; in case of multiple headers, separate the headers with a comma. A request header name defines a name that the service will accept in the request header called 'Access-Control-Request-Headers' for a CORS pre-flight request. The request headers that were accepted will be returned in the response header ‘Access-Control-Allow-Headers’ for the CORS pre-flight request. A service does not need to use any headers, hence the field can be left blank but if a CORS pre-flight request does specify headers in the ‘Access-Control-Request-Headers’ header, then these must be defined in this field or an error status will be returned as stated in the Failed Status Responses. Note The ‘Authorization’ header used by the PROIV REST server is automatically included in the list of acceptable request headers so does not need to be defined here. |
Exp Headers |
Enter the expose header name for the service to expose in response to any CORS service request; in case of multiple expose headers, separate the headers with a comma. The exposed headers will be returned in the response header ‘Access-Control-Expose-Headers’ for CORS simple requests. Currently, the PROIV REST code does not use any exposed headers for the service; however, by using expose headers - any calls to the service will let the caller know what headers are being used so this should only be used to expose ‘public’ information. There is no verification for these headers so their presence or absence will not cause any error status. |
Paths |
A service can have any number of paths defined. You can create a new path by clicking on the + image to the left of the paths field. The paths can be hidden and shown by clicking on the up or down arrow image. |
Path |
The path is the last part of a URL that will be recognized by the server as a request for a RESTful Service. This can be any text but must start with "/". If you do not put "/" at the beginning, the "/" gets added automatically when the service is saved. When you create a new path it behaves as ‘undefined’ value and this is not a valid value and so gets highlighted by turning pink. A path can be deleted by clicking on the – image to the right of the path. A path contents can be hidden and shown by clicking on the up or down arrow image on the right of the path. |
Method |
Each path can have up to four methods (get, put, post & delete) and you can not have duplicate methods in a path. A path must have at least one method so one will be automatically created when you create a new path. You can create a new method for a path by clicking on the + image to the left of the path. A method can be deleted by clicking on the – image to the right of the method, but as there must be at least one method you can not delete a method if it is the only method in the path. The method contents can be hidden and shown by clicking on the up or down arrow image on the right of the method. |
Task |
A RESTful service needs a PRIOV task to perform the service action and each method may have a separate task. You can also use the same task on multiple methods or paths. The task can either be typed in the task field or selected from the drop down list of tasks. The list contains all the RESTful tasks available in the PROIV defined by the service connector. If the list is empty then: your service has no connector, or the PROIV referenced by the connector is not available, or the PROIV referenced by the connector has no RESTful tasks. If your service has a connector and the task you specify is not available then the Build Task to the right of the task is enabled. Click Build Task to trigger the PROIV referenced by the connector creating an empty stub task for the service. If the stub task or function could not be created, then an alert appears with the reason. If a method must have a task so if no task is defined then this field is highlighted by turning pink. |
Description |
Enter any text that describes the task. If you fill the description before you click on the task generate , then this description is assigned to the task stub generated by PROIV. |
Parameters |
A service method requires parameters when it is called. You can define the parameters by clicking the + image to the left of the parameters. The parameters can be hidden and shown by clicking on the up or down arrow image on the right of the parameters. |
Body |
You can define the body data for a service method which requires request body data when it is called. Only methods of type ‘post’ or ‘put’ can define a request body. This body field defines a JSON schema for the request body content and this schema will be used by the test panel and the client generation tool to provide some checking that the request body has the correct structure before a call to the service is performed. |
Responses |
A service method may define the acceptable responses for a service call. You can create as many responses as you want and you do not have to define any responses. The responses contents can be hidden and shown by clicking on the up or down arrow image on the right of the responses. |
Status Code |
A response is defined by its HTTP status code which is a number (For example, 200 is the OK status). You can create a new response by clicking on the + image to the left of the responses. A response can be deleted by clicking on the – image to the right of the status. The responses contents are hidden and shown by clicking on the up or down arrow image on the right of the responses. A response status consists of a description (any text) and a response body schema. The schema field defines a JSON schema in the same way as the request body. |
The PROIV REST server will respond with a failed status code to any request that does not pass the CORS processing. These status code are defined below:
406 Not Accepted – This status code is returned if a CORS pre-flight request is received when CORS processing for the service is not turned on (that is the ‘CORS’ field in the service definition is empty).
403 Forbidden – This status code is returned for a number of CORS failures:
• There is no ‘Origin’ header in a CORS pre-flight or simple request.
• The origin specified in the ‘Origin’ header, in a CORS pre-flight or simple request, did not match any origin specified in the service definition ‘CORS’ field using the rules defined above.
• There is no ‘Access-Control-Allow-Methods’ header in a CORS pre-flight request.
405 Method Not Allowed – The method specified in the ‘Access-Control-Allow-Methods’ header, in a CORS pre-flight request, is not one specified in the service definition.
417 Expectation Failed – One of the headers specified in the ‘Access-Control-Request-Headers’ header, in a CORS pre-flight request, was not defined in the ‘Req Headers’ field in the service definition.
A response with a failed status code will also contain a ‘RWS_Error’ header that holds a string with a short explanation of the reason for failure.
Click Save at any time to store the service on the server. The text just below the Save shows whether the current service is synchronised with the version on the server or if it contains unsaved changes. If a field in the service does not have a valid value then it will be highlighted by turning pink. The fields that this applies to are: connector, protocol, path, and task. Ensure you enter a valid value to remove the pink highlight. |
Topic ID: 400035