The Insuraprise API is a RESTful API. The request and response relies heavily on JSON, base64, and
crypto utilities (both hashing and encryption).
This document is provided as a means to understand what is occuring under-the-hood.
tldr; We provide some [classes and prebuilt libraries](ComingSoon) to make integrating with our
API simple and pain-free.
##### Conventions used in this document
> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
[RFC 2119](http://www.rfc-editor.org/rfc/rfc2119.txt).
# Accessing the API
## URLs
Production
: https://api.insuraprise.com/
Development
: https://dev.api.insuraprise.com/
**NOTE**: When making requests to the Development server, we use a self-signed certificate.
You MAY need to disable any host or peer validation that may be done by default when
making your request.
Example
: https://api.insuraprise.com/
: https://dev.api.insuraprise.com/
## Endpoints
The endpoint will always come after the version number in the URL
: https://api.insuraprise.com/[endpoint]
: https://api.insuraprise.com/hello
For a list of endpoints available to you, see the [Endpoint List](/docs/Endpoints "List of available Endpoints")
## Methods allowed
GET
: query data and return the result
POST
: used to save/update data and returns the saved/updated record
DELETE
: archives the record and returns nothing (success based on 200 response)
**NOTE**: You may not have access to use all the methods listed above. Check the specific endpoint to see what
request methods are available to you.
## Authentication
Each request MUST contain an AuthToken header. The value of this header MUST be
a concatenated string of your application Id, the pipe character (|), and an md5 hash of
your secret key. Our API accepts both upper and lower cased hashes.
Example:
| ApplicationId | MD5 of Secret |
AuthToken: 1234567890abcdef1234567890abcdef|1234567890abcdef1234567890abcdef
## Testing
### Test Endpoints
We provide 2 endpoints to test the basic functionality of our API. This list shows these 2
endpoints and their primary purpose. Below that is a description of the return value for a
particular request method.
/test/methods/hello
: This URL returns unencrypted responses and should be used to test basic functionality
* https://api.insuraprise.com/test/methods/hello
* https://dev.api.insuraprise.com/test/methods/hello
/test/methods/encrypt
: returns encrypted responses and should only be used to test encryption
* https://api.insuraprise.com/test/methods/encrypt
* https://dev.api.insuraprise.com/test/methods/encrypt
/test/methods/exception
: Returns an ApiException to check error handling in the client
* https://api.insuraprise.com/test/methods/exception
* https://dev.api.insuraprise.com/test/methods/exception
### Request Methods
GET
: Any GET request made to either encrypt or hello test endpoints will return an object in the
form of
{"Hello":"World!"}
POST
: POST requests to either encrypt or hello endpoints above will return the data sent in the
body of the request
### API Tester
Along with these test endpoints, we also provide a [test application](/test/home) where you can test the
request you are sending.
# Requesting Data
When making a request to the API, GET and DELETE requests MUST use the query string for the
requested data.
When making a POST, the request object MUST be the only content contained in the body of the POST request.
In neither case SHALL the data be the value of a POST or GET variable. The request object MUST
be raw data.
# Encryption
The default encryption algorithm for the API is AES-128 (also known as Rijndael 128) CFB (Cipher Feedback) mode. The
default hashing algorithm is SHA-256. The secret MUST be used as the both the passphrase for the encryption as well
as the salt for the hashing.
The following steps
MUST be used to create the encrypted request object:
1. The request object MUST be JSON Encoded
2. Once encoded, the payload MUST be hashed using the algorith of your choice (using your secret for the salt). Your algorithm MUST documented in the `algorithms.hash` key and the resulting hash must go in the `hash` key of the request
3. If payload is to be encrypted:
1. The encryption algorithm MUST be recorded in the `algorithms.encryption` key, and the mode MUST be recorded in the `algorithms.mode` key
2. If needed, create an initialization vector
3. Encrypt the payload using the chosen algorithm and mode
4. Prepend the initialization vector to the encrypted payload
4. Base64 encode the payload
5. Payload MUST be recorded in the `payload` key of the request
The final response should resemble the following:
{
"algorithms":{
"hash":"Algorithm used to hash the JSON response.",
"encryption":"Algorithm used in encrypting the data.",
"mode":"Cipher mode used in the encryption"
},
"payload":"The base64 encoded, encrypted response",
"hash":"hash of the original JSON request. This will be used for the integrity check"
}
# Consuming the Response
NOTE: As stated previously, a DELETE request WILL NOT provide a response body. Only a response
code check is needed.
Anatomy of the Response:
{
"algorithms":{
"hash":"Algorithm used to hash the JSON response.",
"encryption":"Algorithm used in encrypting the data."
},
"payload":"The base64 encoded, encrypted response",
"hash":"hash of the original JSON request. This will be used for the integrity check"
}
After making your request, you SHOULD first check the HTTP response code.
Currently, the only success code that we support is 200, anything else is a failure. If the
request fails, there will be no response body. On failure, the API provides a basic response
message to aid in debugging if the issue is a client side issue.
Once you have a successful response, the following steps MUST be followed.
1. JSON decode the response.
2. Check that the algorithms->hash value is what you expect
3. Check that the algorithms->encryption value is what you expect
4. The encrypted response object is contained in the payload property.
5. The payload MUST be base64 decoded
6. If response payload is encrypted:
1. Remove the initialization vector from the begining of the string.
2. Decrypt the string providing the initialization vector and your secret as the passphrase
7. Compare the hash from the hash property to a hash of the decrypted string to ensure integrity.
8. As long as the message is verified, you can then JSON decode the response and start using the response object