Common Behaviors
From API Documentation
Contents |
Access Permissions
Accessing the API requires a username and password, provided by Rezora. To obtain a username and password, contact your Rezora Account Manager.
There are two distinct levels of access to the API, which correspond to user types on the Rezora system in general:
- Company-level
- Agent-level
URI (Uniform Resource Identifier)
The Rezora REST API uses the URI to identify the resource you are attempting to consume.
URI Template: PROTOCOL://DOMAIN/VERSION/RESOURCE_DESIGNATOR.RESPONSE_FORMAT
Example URI: http://api.rezora.com/v1/agents/1234.xml
The URI consists of the following components:
Protocol (required)
The API currently supports the basic HTTP protocol, but will likely switch to HTTPS in future versions to further ensure security.
Example URI: http://api.rezora.com/v1/agents/1234.xml
Domain (required)
The domain of the API is expected to be permanent, and will not change with future versions.
Example URI: http://api.rezora.com/v1/agents/1234.xml
Version (required)
The URI for the API includes a version indicator, used to specify the version of the API for which your application is programmed. This will allow us to continue to offer previous versions of the API without interruption as future versions are released.
Example URI: http://api.rezora.com/v1/agents/1234.xml
Resource Designator (required)
The resource designator portion of the URI is the part which uniquely identifies the resource you wish to consume. It may be comprised of multiple components separated by forward slashes (/). For example, to reference the resource containing all agents in your brokerage, your resource designator would be "agents". To reference the resource for a specific agent, you would include the agent's ID in the resource designator: "agents/1234".
Example URI: http://api.rezora.com/v1/agents/1234.xml
Response Format (optional)
The response format indicator is an optional file extension added to the end of the resource designator (described above). Supported values are JSON, XML, and CSV. A response format indicator included in the URI will supersede the value of an ACCEPT header (described below), if present. If no response format indicator is included in the URI, and no ACCEPT header (described below) is included with the request, the response format will default to CSV.
Example URI: http://api.rezora.com/v1/agents/1234.xml
HTTP Request Headers
The Rezora REST API makes use of several headers sent with the HTTP request for such purposes as authentication, indicating what action is to be taken with the resource specified in the URI, and indicating in what format the data will take in both the request and response.
Example Request: GET /v1/agents/1234.xml HTTP/1.1 Host: api.rezora.com Content-type: application/json
The API makes use of the following headers:
Method (required)
The Rezora REST API makes use of the standard HTTP methods (GET, POST, PUT, and DELETE) to determine the action you wish to perform with the resource you have specified in the URI. Note that not all resources will support all four methods. The actions associated with each method are as follows:
GET
A request sent using the HTTP GET method is used to retrieve or read the data for the specified resource.
POST
A request sent using the HTTP POST method is used to create a new resource of the type specified in the URI.
PUT
A request sent using the HTTP PUT method is used to update an existing resource, as specified in the URI.
DELETE
A request sent using the HTTP DELETE method is used to delete the resource indicated in the URI.
Authorization (required)
The Rezora REST API uses HTTP digest access authentication to validate you username and password before providing access to the requested resource.
Accept (required)
The HTTP ACCEPT header is used to specify the desired format of the response data from the API. The available options are application/xml, application/xml, and text/csv. This option is overridden by the presence of a response format indicator (file extension; see above) in the URI.
Content-type (required)
The HTTP CONTENT-TYPE header is used to specify the format of data being sent as part of the request. The available options are application/xml, application/xml, and text/plain.
HTTP Response Headers
The Rezora REST API provides useful information in several headers sent with the HTTP response.
Example Response: HTTP/1.1 200 OK Date: Sun, 11 Jul 2010 23:00:10 GMT Server: Apache/2.2.12 (Ubuntu) X-Powered-By: PHP/5.2.10-2ubuntu6.4 Set-Cookie: PHPSESSID=e3a81e530b701165d368b77c9ddc6ab6; path=/ Expires: Thu, 19 Nov 1981 08:52:00 GMT Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0 Pragma: no-cache Vary: Accept-Encoding Transfer-Encoding: chunked Content-Type: text/plain
Status
The HTTP STATUS header is used to indicate the status of your request. A list of status codes used by the API and their meanings is provided below.
Status Codes
- 200: The request was successfully processed.
- 204: The request was formatted correctly, but no data was found for the specified resource.
- 400: Your data has failed a validation test.
- 401: Either your username or password are incorrect, or you are attempting to access a resource that is not available for your user type.
- 404: The resource you have requested does not exist.
- 405: The method you are attempting to use (GET, POST, PUT, or DELETE) is not allowed for the resource you have requested.
- 500: The API experienced an internal error while attempting to process your request.
- 501: The method you are attempting to use (GET, POST, PUT, or DELETE) has not yet been implemented, but may be in a future release.
Content-type
The HTTP CONTENT-TYPE header is used to indicate the format of data being sent as part of the response. The format is determined by either the ACCEPT HTTP request header or the response format indicator in the request URI. If no HTTP ACCEPT header or URI format indicator are present in the request, the default response format is text/plain.
