Create REST with JSON service
Last updated
Last updated
This wizard allows you to create skeleton REST services with a JSON payload.
The wizard allows you to select the REST methods and HTTP schemes used, authentication methods and credential storage options.
The starting point is the service name:
The name must be at least 2 characters and may not contain spaces or characters invalid for a URI (such as “:”, “/”, “?”, “&” etc.).
This name forms the endpoint name for the REST service and will also be used as the prefix for all rules and data files created by the wizard to ensure that multiple REST services can be merged into one. For the purpose of this, the service name’s first letter will always be capitalized, however the endpoint name is not case sensitive.
For example: If you enter a name of “helloWorld” and deploy to the proxy server, the endpoint name on the local machine will be:
http://localhost/helloworld
The next step is the repository settings:
The repository name is the location where all the components of the service will be created. This repository must not exist as it will be created with the rights of the user creating it.
You can also choose to add the service to an existing repository. The effect of doing that is that no configuration will be created in the new repository. Instead, the existing repository will have the new repository added as an included repository and the service entry rule will automatically have the new service name added so that the deployment of a single configuration can activate multiple services. The rule set that manages the different services is named ServiceEntry.
You then need to select the methods that you plan to use for the service:
The default is GET and POST. You can of course add missing methods later if you wish, by editing the rule sets. The rule set that governs the available methods is _V1.
The next step is to select the schemes allowed for the service:
You must select at least one scheme. Please note that unless you have a valid certificate in place, testing without http can be verify difficult with modern browsers. You can always change the schemes later by modifying the rule set _Service.
Next you will be asked if you require authentication:
No matter your choice, a rule set named _authentication will be created so that you can modify it later.
If you choose to include Basic or Parameters authentication, a rule set named _CheckUser will be created to verify the provided user name and password.
If you choose to include IP address authentication, a rule set named _CheckIP will be created to verify the incoming IP address.
Your choice of credential store is next:
Depending on your choice, you will be asked some follow up questions. For example, for storage of users or IP addresses in a CSV file, you will be asked to supply some initial users or IPs:
The content of this input field will be written to a data file named _userList for User IDs and password.
The content of this input field will be written to a data file named _ipList for IP addresses.
Please note that passwords in this scenario remain insecure.
Other credential stores will ask you similar relevant questions to establish an initial template rule set. If you choose “Data set” or “Database” as your credential store, you will also be asked to provide a password hashing algorithm:
The default hash salt is randomly derived for maximum security. You can of course change it to suit your environment.
Important: The data set and database options will require your selected database to be added with the relevant driver to the service configuration before deployment. If you are using a database, you must have the relevant table already created and populated.
For all authentication options except LDAP, it is recommended that you create a custom function to allow the service owner to maintain the users and/or IPs stored in the credential store.
Once authentication is defined, you need to provide a JSON formatted error message template:
This template is used to signal service level errors to the user (failed authentication, invalid methods etc.). It is not intended for data level errors, which is represented in the next page:
This is the response template that will be used for each of the methods (GET/POST/PUT/DELETE) upon execution. Data level validation errors should use this template, as should success messages. The status returned should be either “success” or “fail”.
Once your template is completed, there is only one more step, which is to review your choices and click on Continue to generate the repository.
