Common Behaviors

From API Documentation

(Difference between revisions)
Jump to: navigation, search
m (Reverted edits by Zhyaoxiaiw (Talk) to last revision by WikiSysop)
 
Line 1: Line 1:
-
The short hair cut is as popular as ever and more and more women are taking the plunge and sporting ultra-short locks.[http://www.sacsmaindemodedesortie.com/ vuitton sac] , From the heavily textured and spiked to the soft and feminine, there is no doubt that the short hair cut is here to stay and has proven to be one of the most popular hair cut styles among women.[http://www.louisvuittonssalg.com/ louis vuitton oslo] ,
+
== Access Permissions ==
 +
Accessing the API requires a username and password, provided by Rezora. Note that this is not the same as your username and password to the Rezora system itself. 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
 +
API credentials for a company-level account only grant access to company-level resources, and credentials for an agent-level account only grant access to agent-level resources.
-
But how do you know if you should go short with your new hair cut or when you should take the plunge? For most, the answer to these questions is going to be a personal decision, but there are some guidelines that you can follow to help you decide whether or not a short hair cut is for you.[http://www.uggstovlarsalupanatet.com/ boots] ,
+
== Usage Limitations ==
 +
Currently, there is no usage limit in place for the API. However, we do track usage, and reserve the right to institute limitations in the future. In the mean time, we ask that you develop your applications in such a way as to make the fewest API calls necessary to accomplish your goals, and to spread out the calls over time. Your consideration is appreciated.
-
Choosing the right hair cut style should be a joint effort between you and your stylist.[http://www.schmucklinksoflondon.com/ liebe links of london] , With her professional advice as to what will look sensational on you and your personal preference, together you should be able to find numerous new hair cuts that are perfect for your individual personality, tastes and features.[http://www.cheapmontblancs.com/ montblanc pen] ,
+
== URI (Uniform Resource Identifier) ==
 +
The Rezora REST API uses the URI to identify the resource you are attempting to consume.
-
When to go for the short hair cut and when not to
+
'''''URI Template:''''' PROTOCOL://DOMAIN/VERSION/RESOURCE_DESIGNATOR.RESPONSE_FORMAT
-
You should choose a short hair cut if you prefer shorter styles or if you have been thinking about going short for a while. If you have already worn a short hair cut in the past and loved it, then you are one step ahead of the game. Likely, you will have a good idea of what short cuts will look good on you and which cuts will give you the most styling ease and freedom.
+
'''''Example URI:''''' <nowiki>http://api.rezora.com/v1/agents/1234.xml</nowiki>
-
You should not choose a short hair cut just because it is trendy or you saw it on someone else and want to achieve the same effect. While some hair cut styles will look just as great on you as they do on others, getting a short hair cut on a whim is never a good idea. If you see something you like, think about it for a while before deciding to get a new hair cut. Even better - use one of the interactive online hair galleries, to test out the look before you buy
+
The URI consists of the following components:
-
Never get a short hair cut for emotional reasons. Having a bad hair day? Do not cut your hair off in anger. If you do, you may end up fighting with dreaded tresses that are much too short for your particular style. Instead, go for a trim or a style that is just slightly shorter than the one you already have.
+
=== Protocol (required) ===
 +
The API currently supports the basic HTTP protocol, but will likely switch to HTTPS in future versions to further ensure security.
-
How to go short
+
'''''Example URI:''''' <big>'''http'''</big><nowiki>://api.rezora.com/v1/agents/1234.xml</nowiki>
-
If you have never had a short hair cut, you should go shorter gradually to reduce the level of shock experienced with getting a short hair cut and to see if you are going to like wearing shorter styles. Be prepared to experience some level of shock, though, even if you only shorten your style by a few inches.
+
=== Domain (required) ===
 +
The domain of the API is expected to be permanent, and will not change with future versions.
-
Talk to your stylist and decide what type of short hair cut is your ultimate goal. Then, choose several hair cut styles that you can get over the course of a few months that will decrease your hair's length gradually. That way when you finally take the plunge and get the short hair cut you will know that you will be comfortable with it. Nothing is worse than trying to grow out a short hair cut that you hate.
+
'''''Example URI:''''' <nowiki>http://</nowiki><big>'''api.rezora.com'''</big>/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:''''' <nowiki>http://api.rezora.com/</nowiki><big>'''v1'''</big>/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". URIs for all available resources are given on the individual [[Resource_Definitions|Resource Definition]] pages.
 +
 
 +
'''''Example URI:''''' <nowiki>http://api.rezora.com/v1/</nowiki><big>'''agents/1234'''</big>.xml
 +
 
 +
=== Response Format (optional) ===
 +
The response format indicator is an optional file extension added to the end of the [[Common_Behaviors#Resource_Designator_.28required.29|resource designator]]. 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 [[Common_Behaviors#Accept_.28required.29|ACCEPT header]] is included with the request, the response format will default to CSV.
 +
'''''Example URI:''''' <nowiki>http://api.rezora.com/v1/agents/1234.</nowiki><big>'''xml'''</big>
 +
 
 +
== 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
 +
Authorization: Digest username="YOUR_USERNAME", realm="Rezora API", nonce="4c487da82df10",
 +
  uri="/v1/agents/1234.xml", cnonce="MjMxATNz", nc=00000001, qop="auth",
 +
  response="a6767615fab72a0c9d64d4b01df69db2", opaque="e24302732637d79c3b77fa62483ec0b7"
 +
Host: api.rezora.com
 +
Accept: text/csv
 +
Content-type: text/plain
 +
 
 +
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 your 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 [[Common_Behaviors#Response_Format_.28optional.29|response format indicator (file extension)]] 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. Note that, while the Content-type header is required for all request methods, data is only sent with POST and PUT requests.
 +
 
 +
== HTTP Response Headers ==
 +
The Rezora REST API provides useful information in several headers sent with the HTTP response.
 +
 
 +
'''''Example Response Headers:'''''
 +
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
 +
Transfer-Encoding: chunked
 +
Content-Type: text/csv; charset=UTF-8
 +
 
 +
=== Status ===
 +
The first line of the HTTP headers includes a numeric code, which is used to indicate the status of your request.
 +
 
 +
'''''Example Status Header:'''''
 +
HTTP/1.1 200 OK
 +
 
 +
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 [[Common_Behaviors#Accept_.28required.29|ACCEPT HTTP request header]] or the [[Common_Behaviors#Response_Format_.28optional.29|response format indicator (file extension)]] in the request URI. If no ACCEPT header or response format indicator are present in the request, the default response format is text/csv.
 +
 
 +
'''''Example Header:'''''
 +
Content-Type: text/csv; charset=UTF-8
 +
 
 +
== About Output Data ==
 +
All dates are displayed as UTC (GMT), unless otherwise noted. All output data is UTF-8 encoded. Data in JSON and XML formats follow the standard rules of escaping reserved characters, encoding entities, etc. as indicated by their respective standards.  As there is no standard for the CSV format, here are the formatting rules we are using for our output:
 +
 
 +
* '''Field delimiter:''' |
 +
* '''Line terminator:''' \r\n
 +
* '''Quoting:''' all fields are quoted
 +
* '''Quote character:''' "
 +
* '''Escape Character:''' \

Latest revision as of 14:20, 1 March 2012

Contents

Access Permissions

Accessing the API requires a username and password, provided by Rezora. Note that this is not the same as your username and password to the Rezora system itself. 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

API credentials for a company-level account only grant access to company-level resources, and credentials for an agent-level account only grant access to agent-level resources.

Usage Limitations

Currently, there is no usage limit in place for the API. However, we do track usage, and reserve the right to institute limitations in the future. In the mean time, we ask that you develop your applications in such a way as to make the fewest API calls necessary to accomplish your goals, and to spread out the calls over time. Your consideration is appreciated.

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". URIs for all available resources are given on the individual Resource Definition pages. 

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. 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 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
Authorization: Digest username="YOUR_USERNAME", realm="Rezora API", nonce="4c487da82df10", 
 uri="/v1/agents/1234.xml", cnonce="MjMxATNz", nc=00000001, qop="auth", 
 response="a6767615fab72a0c9d64d4b01df69db2", opaque="e24302732637d79c3b77fa62483ec0b7"
Host: api.rezora.com
Accept: text/csv
Content-type: text/plain

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 your 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) 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. Note that, while the Content-type header is required for all request methods, data is only sent with POST and PUT requests.

HTTP Response Headers

The Rezora REST API provides useful information in several headers sent with the HTTP response. 

Example Response Headers:
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
Transfer-Encoding: chunked
Content-Type: text/csv; charset=UTF-8

Status

The first line of the HTTP headers includes a numeric code, which is used to indicate the status of your request. 

Example Status Header:
HTTP/1.1 200 OK

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 (file extension) in the request URI. If no ACCEPT header or response format indicator are present in the request, the default response format is text/csv. 

Example Header:
Content-Type: text/csv; charset=UTF-8

About Output Data

All dates are displayed as UTC (GMT), unless otherwise noted. All output data is UTF-8 encoded. Data in JSON and XML formats follow the standard rules of escaping reserved characters, encoding entities, etc. as indicated by their respective standards. As there is no standard for the CSV format, here are the formatting rules we are using for our output:

  • Field delimiter: |
  • Line terminator: \r\n
  • Quoting: all fields are quoted
  • Quote character: "
  • Escape Character: \
Retrieved from "http://api.rezora.com/documentation/index.php?title=Common_Behaviors"
Personal tools