REpresentational State Transfer (REST) is a set of guidelines and best practices for API design. We believe in pragmatic REST design. In other words, our API follows RESTful principles, deviating only to make life easier for end users (you). RESTful principles include:
When to use authentication via login: Login-based authentication is appropriate when communication with Honest Renter's servers will be entirely through your user's browser via AJAX. Honest Renter will manage session creation, authentication, and expiry. The key advantage over secret key authentication is its simplicity. Your website only needs front end files (e.g., html, css, javascript). You don't need to create or maintain any server-side scripts (e.g., php, asp, python, .net). You don't need to store any usernames or passwords in your own database. We take care of all the tricky bits for you. If you are a landlord or small property management company, you probably want authentication via login.
What do I need to start? You need an apiKey. Contact us to have us generate one for you.
Initial authentication: To log in a member, create a new session by posting his/her username and password to https://api.honestrenter.com/members/session. To log in an applicant, create a new session by posting an invitation code's value to https://api.honestrenter.com/applicants/session
Failed login: When there is no member or applicant matching the provided info, a 404 not found error is thrown. When the password is incorrect, a 400 error is thrown. After 10 failed attemps, a 422 Unprocessable Entity error is thrown, and the member is temporarily locked, preventing anyone from logging in as that member. The IP address will also be locked, temporarily preventing that IP address from logging in to anyone's account.
Successful login: If the login details are correct, the server will respond with a HTTP status code of 200. The response body will contain the corresponding member or applicant object in JSON format. The response header will contain two parameters to be used for authenticating subsequent API calls:
Subsequent authentication: After login credentials have been verified by the API, subsequent calls are authorized and authenticated using the session and authentication token respectively. The HONR-Session and HONR-Authentication-Token should be included in all future request headers for that person's session.
Lifetime of sessions: Sessions expire after about 60 minutes of inactivity. Activity can renew the session. If a session is more than 5 and less than 60 minutes old, any new request will produce a new HONR-Session and HONR-Authentication-Token returned in response headers. Those new values can be used instead of the old ones to extend the life of the session so that the person can continue working without having to re-supply their login credentials. To avoid sessions being renewed forever, there is a maximum life imposed on a session. A session is only renewable for up to 3 hours. After that, login credentials will have to be provided again. These lifetime limits on sessions help improve security by limiting the value of hijacking a session.
HTTPS required: To ensure that session credentials remain safe, all API requests must be made over HTTPS. Any call made over plain HTTP will fail.
When to use secret key authentication: Larger companies may already have online platforms that manage user login/authentication. When you have a service that already verifies login credentials, you probably don't want the hassle of a second login just for Honest Renter. Instead, you can generate API request headers containing all necessary credentials using your own back end scripts. The key advantages of using secret keys over login authentication are that:
What do I need to start?
Initial authentication: A back end script (e.g., php, asp, python) on your server generates session information and uses your secret key to produce a valid authentication token. Include those in the HONR-Session and HONR-Authentication-Token HTTP headers of your request. See the sample PHP code (on the right) for producing the session and authentication token.
Failed authentication: A 401 error is thrown when you did not use the right secretKey, or when the authentication token did not match the session information, or when the session has expired.
Maximum session length: Expiry dates that are more than 3 hours in the future will be reset to 3 hours in the future. If the renewableUntil date is more than 24 hours in the future, it will be reset to 24 hours in the future.
What's in a session: Sessions are the same for both authentication via login and authentication via secret key. They describe who is logged in, the level of authorization granted, when the credentials will expire, and the API key used to generate the request. A typical value looks like {"apiKey":"jU89Bv9KL3tYzHm", "authorization":"member", "expires":1429940443, "person":"cykKrHNCjQ", "renewableUntil":1429949443}.
Generating the authentication token:
Subsequent authentication: You can continue using the same HONR-Session and HONR-Authentication-Token to make additional requests up to the expiry time of the session. The requests could come directly from your server, or from a user's browser.
HTTPS required: To ensure that session credentials remain safe, all API requests must be made over HTTPS. Any call made over plain HTTP will fail.
Keep the secretKey secret: As the name implies, is is important that your secretKey is kept secret. Store it somewhere outside of your website's document root. The secretKey should never be sent in any headers. Someone who knows your secret key could impersonate any of your users on Honest Renter. If you believe someone inappropriate may have gained access to your secret key, let us know so that we can generate a new one for you.
When response headers to a browser contain HONR-Session and HONR-Authentication-Token information, you should save that information. Subsequent API requests from the client's browser must include the session info and authentication token.
There are two main options for saving the information to client's browser:
Cookies: You can save the information in a cookie. One word of caution is that once a cookie is set, it is automatically included in all request headers for all file types. That's fine if everything is loaded over a secure https connection. However, if you load a stylesheet or image over http, you could potentially expose the session information. Exposed session information could allow someone to log in as that person for a few hours. That risk can be mitigated by setting the cookie as secure so that it will only be transmitted over https. The take home message is that if storing session information in cookies, make sure all files are loaded over secure https connections, or set the secure flag.
JavaScript's sessionStorage: JavaScript's sessionStorage in an HTML5 alternative to cookies. Unlike cookies, sessionStorage values are not included automatically included in all request headers. This helps reduce the risk of accidental exposure. Note that iOS disables sessionStorage during privacy mode. To avoid errors in iOS privacy mode, best practice is to detect whether sessionStorage is currently enabled. When sessionStorage is disabled, you can use cookies as a fall back solution.
We use standard HTTP response codes to indicate success or failure of API requests. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error due to the information provided in the request (e.g. a required parameter was missing, the logged in person lacks permissions required to complete the request, etc.). Codes in the 5xx range indicate an error on Honest Renter's servers.
Successful requests (in the 2xx range) return objects in the "data" namespace. Failed requests (in the 4xx or 5xx range) return objects in the "error" namespace.
Errors are returned in the request body as a JSON formatted object. The "message" property contains text suitable for you to display to end users.
| 200 - OK | Everything worked as expected. |
| 201 - Created | The request has been fulfilled and resulted in a new resource being created. |
| 204 - No content | The server has successfully fulfilled the request but does not need to return a body. |
| 400 - Bad Reqest | Something went wrong when posting the information. This generic error only occurs when none of the other more specific 400 level error types apply. Check the message returned for details. |
| 401 - Unauthorized | Request not completed because it lacks valid credentials for the target resource. The session may have timed out or been unset. The person needs to log in again. |
| 403 - Forbidden | The person making the request lacks permissions to perform the requested action on the requested object. A different user (e.g., account administrator) may need to perform the action instead. |
| 404 - Not Found | The requested object doesn't exist, or the server cannot confirm the object's existence for the logged in user. |
| 405 - Method Not Allowed | A request was made of a resource using a request method not supported by that resource; for example, using GET on a form which requires data to be presented via POST, or using PATCH on a read-only resource. |
| 408 - Request Timeout | The request wasn't processed because it did not complete in time. It's safe to try again. |
| 412 - Precondition Failed | Missing a required parameter in the GET or POST data. Check the front end javascript to make sure all required values are being submitted. You may want to alert yourself whenever a 412 error is thrown because it likely indicates a bug in your code. |
| 418 - Api Connection | Failed to connect to the Honest Renter server for performing the API request. |
| 419- Already Completed | The response cannot be modified because the assessment for that administration has already been marked as completed. |
| 422 - Unprocessable entity | A value entered by someone on a form was invalid (e.g., invalid email address). You should display a message to the person so he or she can correct the error. |
| 500, 502, 503, 504 - Sever Errors | Something went wrong on Honest Renter's end. For most errors, our technical support team is automatically notified and we'll fix it promptly. |
Chained objects: Objects are often chained, meaning they are properties of other objects. For example, a person object contains an emails property which lists all the email objects associated with that person. Chained objects can be expanded using the expand request parameter. Expanding allows multiple chained objects to be retrieved in a single API call.
Available everywhere: The expand parameter is available on all API requests. All chained objects are expandable.
Always use JSON: Values of the "expand" paramater must always be in valid JSON format. To expand a person's email addresses, the expand parameter would be expand='["emails"]'. To expand both email addresses and phone numbers, the request would be expand='["emails","phones"]'. You can also do nested expansion requests. A request to expand both emails and phones properies of a pet's owner would be expand='{"owner":["emails","phones"]}'.
Dots: Dots are a convenient shorthand for nested expansions. A request to expand=["owner.emails"] of a pet will expand the owner property into a full person object, then expand the emails property for that person into a full list of email objects. You may find the dot notation more readable than writing out the equivalent JSON: expand={"owner":["emails"]}.
Fetching a list: For most objects, making a "GET" request on the collector returns a list of objects. For example, a "GET" request to https://api.honestrenter.com/pet-types returns a list of pet types.
Filters: Filters specify which objects to return in the list. Filters are listed in the query string.
Ampersands (&) Ampersands are equivalent to an SQL "AND" operator. When filtering pets, the filter "owner=Ted" searches for pets where the owner property has the value "Ted". The filter "type=1" restricts the lookup to pets where the type property has the value 1 (i.e., dogs). The filter "owner=Ted&type=1" will return dogs owned by Ted.
Commas Commas are equivalent to an SQL "OR" operator. The filter "type=1,2,3,4" will match pets where the type property has the value 1 or 2 or 3 or 4.
Combining ampersands with commas You can combine ampersands and commas for more complex queries. The filter "owner=Ted,Fred,Jim&type=1,2,3,4" will match any pets owned by Ted, Fred, or Jim having the type value of 1 or 2 or 3 or 4.
Limits Want to return only the first 10 results? Specify a limit of 10. When no limit is provided, the system uses the maximum limit for that object. For most objects, the maximum limit is 100. The limit used in the query is listed in the meta-data of the returned results.
Offset Offset allows you to start with the nth object in the returned list. For example, offset=20&limit=10 will display objects 20 through 30 in the list of matched results. When no offset is provided, defaults to 0. The offset used in a query is listed in the meta-data of the returned results.
Wish you could make the API output just the fields you want? No problem! Just include a comma-sparated list of fields in the query string. Only those fields will be output in any objects (including chained objects) returned by the API.
All API requests must include "application/vnd.honestrenter.v1+json" in the Accept header. The "v1" at the end stands for "version 1." It tells our API how to prepare a response consistent with your system's expectations. The +json lets our system know to respond in json format. Currently we only support responses in JSON format, though we may add other options in future.
Minimizing changes: Changes are a pain in the neck for everyone. They're also a necessary evil. We'll make every effort to minimize the number of backwards incompatible changes to our API. When we have to release a backward-incompatible change, we will release a new version. The current version is version 1.
Changelog: All changes will be noted in our changelog, viewable on this API documentation. Currently there are no changes to report.
No changes to report yet!