![\"\"](\"http://www.nedcosafe.com/pict/app.png\")
\t
\tImplements all CRUD operations (CREATE, READ, UPDATE, DELETE).
\n\tAutomatically imports the database structure and create a metadata of your database.Single point access, accept POST/PUT/GET/DELETE http methods and respond with a JSON data object.
\tBasic operations can be used from the start:
\n\tThe servers accepts batch of different commands at once and uses transactions by default.
\n\tInject your code BEFORE and AFTER operations in order to customize access to each action.
\n\tCreate queries and access them with simple GET commands.
\n\tCurrent version can be set to access data from one PostgreSQL server. If you need to access different PostgreSQL servers from a single point please check the enterprise version availability with support team at support@nedcosafe.com.
\n\tThis RESTful API server can be used to offer WEB services for various kind of applications and devices over HTTP/HTTPS protocol like WEB, mobile or IoT applications that consumes WEB services.
\n\tOne solution can scale by adding new API servers, the configuration can be shared within instances. To scale the solution a Load Balancing server is required and next just add or drop API instances to it.
\n"},{"title": "About","id": "about","content": "\t
\n\tLicense
\t\t\t\t\tThe MIT License (MIT)
\n\t\t\t\t\t\t\t\t\tCopyright (c) 2015 Q-Bis Consult S.R.L.
\n\t\t\t\t\t\t\t\t\tPermission is hereby granted, free of charge, to any person obtaining a copy
\n\t\t\t\t\tof this software and associated documentation files (the "Software"), to deal
\n\t\t\t\t\tin the Software without restriction, including without limitation the rights
\n\t\t\t\t\tto use, copy, modify, merge, publish, distribute, sub-license, and/or sell
\n\t\t\t\t\tcopies of the Software, and to permit persons to whom the Software is
\n\t\t\t\t\tfurnished to do so, subject to the following conditions:
\t\t\t\t\tThe above copyright notice and this permission notice shall be included in
\n\t\t\t\t\tall copies or substantial portions of the Software.
\t\t\t\t\tTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
\n\t\t\t\t\tIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
\n\t\t\t\t\tFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
\n\t\t\t\t\tAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
\n\t\t\t\t\tLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
\n\t\t\t\t\tOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
\n\t\t\t\t\tTHE SOFTWARE.
\tAbout
\n\tDeveloped and maintained by:
\n\tQ-Bis Consult S.R.L.
\n\twww.qbis.ro
\n\tsupport@qbis.ro
\tNEDCO SAFE S.R.L.
\n\twww.nedcosafe.com
\n\tsupport@nedcosafe.com
\tDANCO S.R.L.
\n\thttp://www.dancosolutions.net/
\n\toffice@dancosolutions.net
\t
\n\tDependency
\n\tRAPID API is a NodeJS application based on Express server framework. It uses next modules:
\n\tRESTful API for PostgreSQL
\n\tRequirements:
\n\t- OpenSSL shuld be installed before in order to allow the server to create it's first self-signed SSL certificate.
\n\t- for Linux you will need to set your computer to accept Node opening lower ports (80/443 ...) without root access, next code works for Ubuntu
\t sudo apt-get install libcap2-bin
\n\t sudo setcap cap_net_bind_service=+ep /usr/local/bin/node
\tUnzip the server archive.
\n\tRun the server with:
\n\tThe server can be managed at: https://<server Ip or domain name>
\n\tIt will generate a self-signed SSL certificate at start until you will provide an authorized one.
\tIf OpenSSL can not be found, you may need to provide a SSL certificate otherwise the server will not start.
\n\tPut the certificate into "ssl" folder as service.crt and service.key files. The SSL certificate is a PEM encoded crt file.
\n\t
\n\tYou can change the server port and protocol (HTTP/HTTPS) for API access from settings page.
\tPlease check the SSL documentation page for more information.
\n\tSee SETTINGS chapter for this server SSL setup after installation.
\n\t
\n"},{"title": "Start page","id": "start_page","content": "\tServer information page.
\n\tThis page will display server status or required actions to setup the server.
\n\t![\"StartPage\"](\"http://www.nedcosafe.com/pict/startpage.png\")
\tApplication server setup starts here.
\n\tBe sure that you can access your PostgreSQL database server by setting your firewalls and security rules to alow access from the application server computer/vpc. For Amazon RDS you will need to setup properly your database security group.
\n\tFirst action that comes with a fresh new server is to set its data access information. It is a short wizard that ask for your database connection credits. If the database is not found or can not be reached an error message is displayed.e
\n\tDatabase server:
\n\tIn order to set access to a PostgreSQL server next information are required:
\n\tWhen used with Amazon RDS there are settings to be made on AWS console related to access security. Please check the AWS documentation.
\n\tAll database server REST API configuration is stored in a database on the used PostgreSQL server (rcfg). By storing nothing important locally the system can scale simple adding new servers.
\n\tFrom settings page you can change administrator password or set an address for another PostgreSQL server.
\n\tSystem:
\n\tAdministrator - set the administrator name and password
\n\tRAPID API - control the RESful API server (set properties, start /stop).
\n\tTOKEN password - used for API authorization by default. The authorization method can be changed into RULES page at choice, code for JWT authorization is provided and samples for basic authorization.
\n\tSSL Certificate - set/view the used SSL certificate.
\n\tAfter some changes the server is restarted automatically to apply changes that require restart (SSL, port ...)
\n"},{"title": "Security","id": "security","content": "\tSecurity is one of most concerns in today world, dealing with databases over WEB is a potential security risk that need attention from the very start of your WEB application project.
\n\tRAPID servers uses HTTPS protocol for data communication and flexible authorization methods implementing JWT by default.
\n\tAuthorization is based on "Authorization" header provided with each request, the server is a RESTful server and does not stores any user session. It is advised to use JWT for API access, however the authorization method can be changed to any of your choice by modifying the AUTHORIZATION js file (rpdauth.js) using RULES page.
\n\tOne SSL self-signed certificate is created when the server is started first time, it can be changed at any time using settings page.
\n\tADMIN interface has one administrator only and it is protected by a basic authorization, in plus an IP filter list can be set to allow access to ADMIN module only from particular locations.
\n\tThe server will open two ports, one for administration witch is 443 and 3330 for API access. It is recommended to use another port than 443 for API access as 443 port is generally more exposed to benign crawlers or malicious random attack. Change API port in settings page.
\n\tUse "IP filtering" in settings page to protect better the ADMIN interface.
\n"},{"title": "SSL","id": "ssl","content": "\thttps://en.wikipedia.org/wiki/Transport_Layer_Security
\n\tFor a good security compliance in a production environment and to be sure that your REST API server will be accepted by all clients you will need to set a certified SSL certificate issued by an authorized CA (Certificate Authority).
\n\tSSL certificates can be issued for an IP or a Domain name, depending on your requirements you may chose from different CA providers.
\n\tOpenSSL can be used to create self signed SSL certificates or certificate requests. See next article for details.
\n\thttps://www.digitalocean.com/community/tutorials/openssl-essentials-working-with-ssl-certificates-private-keys-and-csrs
\tAt start the server will create automatically a self signed certificate to protect the administration pages. This certificate can be used safely at start as it is unique and good enough to protect most sensitive information.
\n\tIn "development" mode, the REST API server can be used with HTTP unprotected protocol, however when the server is set in "production" mode a verified certificate is needed, otherwise the server can not be used as a cross origin resource for WEB applications and mobile applications based on WEBkit.
\n\tSSL certificate can be set in SETTINGS page. There will be needed a PEM encoded CRT file and it's private key. The private KEY should have no password protection.
\n\t
\tRAPID server is a RESTful API server, it can be set to accept any kind of authorization method by allowing custom code.
\n\tSince the server can be used in a SOA infrastructure the best option for authorization is token based.
\n\tRAPID API exposes by default a JSON WEB TOKEN authorization method.
\n\thttps://github.com/auth0/node-jsonwebtoken
\tJWT authorization
\n\tTo set up properly the system you will need to change the default JWT private key to the same key of your applications that uses this API server (the token emitter).
\n\tToken required by RAPID is at least "user", the JWT can contain a lot of other information you may need for your application.
\n\tThe "user" information can be used further in your RULES code for different purposes. If you will not need to differentiate your users access you may use same token for all interfaces regardless who uses the application.
\n\tDevelopment tokens can be created in TOKENS page, (new tab/tokens).
\n\tWhy JWT?
\n\tIn a RESTful world each request is not related to any previous one, the server does not stores any user related information, on the other hand when used as an API provider one server may be not the same as the WEB application server so cookies can not be used properly, the solution is to provide an authorization code for each request. If authorization need to be confirmed with another service that will cost processing power. JWT solve this by checking the authorization token server side based on same settings as the token emitter. Using it along with HTTPS this is a safe standard industry authorization method.
\n\tTokens are accepted as authorization headers or query parameter. However that can be changed in AUTHORIZATION rules (javascript code).
\n\tor
\n\tBASIC authorization
\n\tA basic authorization is based on an authorization header:
\n\tAuthorization: Basic <base 64 code (user:pass)>
\n\tIt is safe when used with HTTPS, but still the username and password need to be checked against a database.
\n\tAny authorization like OAUTH2.0 or third-party from Facebook or other providers can be implemented by changing the AUTHORIZATION rule with your own custom Javascript code.
\n"},{"title": "JSON WEB TOKENS (JWT)","id": "json_web_tokens_jwt","content": "\tJSON WEB TOKENS or JWT
\n\tA standard authorization method for WEB API's.
\n\tIt uses the WEB request Authorization header to provide the token.
\tOne token is an encrypted JSON. The emiter (authorization server) should have the same private key with the API service server, one that will check the token validity.
\n\tTokens can have any required attributes, like USER, EMAIL, ID's, EXPIRE.
\n\tRAPID API server implements authorization by checking each request with the rpdauth.js auth function (see AUTHORIZATION page). The JWT Authorization token is decrypted and added to the client request as it is. By simple decrypting the token, the authorization is passed. Later any other rule can check the decrypted token object properties for application purposes like access rights, logs and any needed.
\n\tIn BEFORE RULES can be used like:
\n\n\n
\t"checkAll" BEFORE rule can be used to check if token is expired. This will apply to all requests.
\n\tCross Origin Resource Sharring a default standard for a Service Oriented Arhitecture.
\n\tRAPID API is CORS enabled by default.
\n\tMore detail related to CORS can be found at https://en.wikipedia.org/wiki/Cross-origin_resource_sharing.
\n\tAn API server used as a cross origin resource always should use an verified SSL certificate, otherwise the client web browser will not accept the connection at fist place.
\n\tIt is not reccomended to open and use a REST API server without encryption (HTTPS protocol).
\n\t
\n"},{"title": "API - CRUD operations","id": "api_crud_operations","content": "\tAPI
\n\tCreate, Read, Update, Delete or CRUD refers to basic operations on databases, in plus there are options to query the database and run a batch of operations at once in a transaction.
\n\tThe server do not accept free SQL's via REST API as this can be a security issue, instead each SQL you may need should be declared as SQL statement and used via a REST command. The server uses JSON data format for requests and responses. Next are described HTTP commands that can be used with the REST API server.
\n\tAll CRUD operations are ready to be used without additional settings after server configuration, however if you will need more it can be done with rules for each operation and table in your databases (before and after rules).
\n\tAll requests should provide next headers, one token can be set using TOKENS page, please check JSON WEB Tokens page. Authorization method can be changed.
\n\tserver_address: your server address including port like myserver.com:3330
\n\tCREATE
\n\tInsert a new record.
\n\tRequest:
\n<server address>/rapid/<table>\tRAPID will add the primary key if not sent in request, the primary key is a standard GUID of … characters. RAPID check that each field in request belong to the table and each mandatory field in the table it is in the request (exception the PK that can be created if missing). After compliance the request is prepared and sent to the RDBMS as INSERT statement.
\n\tSample CREATE (POST) request:
\n\tPath:
\n\nhttp://testserver.com/rapid/users\n\tRequest body:
\n\n{"username":"test1","firstname":"John","lastname":"Smith","email":"someone@aol.com"}\n\tREAD
\n\tRead a record by primary key.
\n\tFIND : Check for one record, it is enabled by default and no further actions are required to make it working.
\n\tQUERY : To return more data from the same table or from more tables, it needs preparations in form of a SQL statement saved into SQLS configuration table.
\n\tFIND
\n\tRAPID uses this to check if a record exist and return its data.
\n\tRequest:
\n<server address>/rapid/<table>?<PK>=<key value>\tThe response is the entire row in JSON format. If you will need to control further the response in order to not return some fields just set your rules into rpdafter.js for yourtableFind (SailsJs/js/rpdafter.js).
\n\tWithout parameters (pky) will return a maximum of 1000 unsorted records from the table.
\n\tUPDATE
\n\tSame as CREATE, exceptions are:
\n\tReturns JSON
\n\tDELETE
\n\tRequest:
\n<server address>/rapid/<table>?<PK>=<key value>\tCan be used to mark a record as deleted instead really delete. To do that you need to have one boolean field named ‘deleted’ into the table. (Please set your SQL Queries accordingly if you are using ‘deleted’ field mark)
\n\tThe response is a JSON with DELETE command result not the deleted row. Functions for before and after actions can be set into rpdafter.js and rpdbefore.js (see next chapters for details)
\n\tQUERY
\n\tAllows you to run a SQL statement and return the response as JSON.
\n\tQueries can be set using the application "Queries" option from a new tab. Check also in page help.
\tSample SQL:
\n\tRAPID uses ‘&’ wild-card here to mark a parameter, this conventions comes back from ODBC or ADO queries standard. The SQL statement should respect the RDBMS standards and syntax.
\n\nselect users.firstname, users.lastname, users.email,\nassets.assetname,assets.description\nfrom assets inner join users on assets.uid = users.id\norder by users.firstname\nwhere assets.catid = &selcatid\n\tRequest:
\n<server address>/rapid/rpdquery?csql=<sqlname>&<par1>=<val1>&<par2>=<val2> ...\tRestrictions:
\n\tSample request:
\n\nhttp://54.69.200.49:1337/rapid/rpdquery?csql=test&limit=50&offset=0\n\tThe result is in JSON format.
\n\tQueries
\n\tImplemented CRUD operations offers data access by default. An API server should not accept SQL requests from the client as it is not secure enough.
\n\tRAPID solves this by storing server side SQL statements that can be later accessed.
\n\tUse QUERIES page to manage queries list (write/test SQL's). Results are always sent in JSON format.
\n\t
\nhttps://yourserveraddress:port/rapid/rpdquery?csql=nameofthesql&[par1=val1&par2=val2] ...&limit=0&offset=0 \tSample front-end Angular request object:
\n\t
\n\tCRUD batch operations
\n\tRAPID can be used to save (create,update,delete) more records from different tables even from different databases using one request. It can use two methods for its purpose, one that opens a transaction per database and the second one that threat each dataset row as an individual request and returns errors in case as a separate object into the response.
\n\tRequest:
\n<server address>/rapid/up_data<server address>/rapid/up_tdata\tRequest body (JSON):
\n\tAn object “data” of tables where each table is an array of row objects. Each row should have a property rpdstatus = -1,0,1,2
\n\tAdd as many tables and row records as your system can load. It is useful to save documents like invoices, orders and any alike in one shot. This approach where widely used by traditional client server desktop applications.
\n\tSample:
\n\n{"data":{"attach":[\n {"id":"a123","file":"max1","type":"txt","rpdstatus":1},\n {"id":"b123","file":"max2","type":"txt","rpdstatus":2}\n ]\n }\n}\n\tResponse:
\n\tA JSON almost identical with the request, rpdstatus will be set to 0 for solved records and 9 if an error where encountered (up_data path), for each error a descriptive row is added to the response dataset. If the request was sent to be transactional (up_tdata path) in case of any error the error is returned and the traqnsaction is rooled back, these hapens even we are using tables from more than one database within the same dataset.
\n"},{"title": "Sample testing","id": "sample_testing","content": "\tWe recommend Firefox and Firefox RestClient for direct testing.
\n\tNext image present an Create request with Firefox RestClient:
\n\tCREATE uses POST method and a JSON key values object parameters body of fields and values to insert.
\n\tYou will need a token in order to set properly the authorization header (use Headers and Authorization / token). Headers can be saved for later use, same for requests.
\tCreate will return created record as OK result. Useful when you do not send an ID rather retrieve one from the server.
\n\tThe server always add an unique UUID if one is not provided.
\t
\n\t![\"\"](\"http://www.nedcosafe.com/pict/sample.png\")
\t
\n"},{"title": "Rules (before & after)","id": "rules_before_after","content": "\tRULES for CRUD operations
\n\tRules editor offers javascript syntax checkings and final validation before overwrite one of the server js files.
\n\tBefore rules refers to functions that can be set to run before an CRUD operation of RESTful API.
\n\tCRUD operations are based on client REQUEST, depending on the request type there each request comes with parameters or attributes. Before rules are in place to check or alter the request parameters to provide a better option for your application API.
\tBefore rules are implemented as module from "rpdbefore.js" file found on "js" folder of your server root. When is edited it is copied to "js/work" folder and saved only after it is checked against gross errors that can stop the start process of your server.
\n\tFunction naming rule is simple, the function name is formed by table name (lowercase) and action name proper case (Create, Find, Update, Delete).
\n\tFunction parameters:
\n\tSample:
\n\nmodule.export = {\n \t\t...\n\t \tusersCreate: function(req,atr,next){\n\t \t\tatr.id = myfunction(); // create custom ID\n\t \t\tif (!atr.email){return next({error:"email required"});\n\t \t\tnext()\n\t \t},\n \t\t...\n \t}\n\tThe checkAll before rule runs on top of all requests if it is set (found in module).
\n\tAfter rules refers to functions that can be set to run after a CRUD application of RESTful API. It is useful to check and change the request result. Same model as "BEFORE" rules.
\n\t
\n\t
\n"}],"use_sub": false,"logo": "","favicon": "","customcss": "","easing": "swing","easingduration": "100","bgimage": "","bgrepeat": "repeat","bgattachment": "scroll","bgcolor": "FFFFFF","textcolor": "383838","linkcolor": "0000FF","hrcolor1": "D3EFF0","hrcolor2": "FFFFFF","btncolor": "FFFFFF","btncolor1": "0088CC","btncolor2": "0044CC","sidebarbgimage": "","sidebarbgrepeat": "repeat","sidebarbgcolor": "DDDDDD","sidebartextcolor": "222222","sidebarlinkcolor": "444444","sidebaractivecolor": "444444","sidebaractivetextcolor": "DDDDDD","sidebarhrcolor1": "AAAAAA","sidebarhrcolor2": "EEEEEE","cufon": "","documentationttype": "default","itemURL": "","sendJSON": "","sendZIP": "","sendPWD": ""}