User:Drakken Keisterbane/CREST: Difference between revisions

Line 26:

It is important to state that applications will always be served the ''newest'' version of a representation by default, so that new applications use the newest version. It is very important to explicitly state which version of a given representation you are relying on in order to ensure the continued functionality of your applications, especially if these rely on the structure of a particular version of the representation.

You can specify which version of a representation(s) you'd like your application to deal with by using the '''Accept''' header to specify what version of a representation you want to receive and the '''Content-Type''' header to specify what version to send out.

You can specify which version of a representation(s) you'd like your application to deal with by using the '''Accept''' header to specify what version of a representation you want to receive (used in HTTP GET requests) and the '''Content-Type''' header to specify what version to send out (used in HTTP POST and PUT requests). More information on these these headers can be found [http://en.wikipedia.org/wiki/List_of_HTTP_header_fields here].

===Representations in Code===

Representations are formatted as [http://www.json.org/ JSON] (JavaScript Object Notation) objects, containing name/value pairs, nested objects and arrays. Some name and value pairs are optional, and can be omitted by senders when not necessary. Other name/value pairs have default values assigned to them if a value is not explicitly assigned.

There are special names used across all representations that have special significance, and thus can be relied on to be consistent across all versions of a given representation.

* '''href''': Intended to be used as a URI to an external resource.

* '''name''': Intended to be used as a localized, human-readable name for a given resource.

* '''id''': Intended to be used as an identifier for a given resource, which is not human-readable.

The values used in these representations can be of various JSON data types; these are described below.

* '''string''': A JSON string. ''Ex:'' "John Doe"

* '''number''': A JSON number - the equivalent of double precision floating point format in Java and other languages. ''Ex:'' 65.1231415

* '''int''': A JSON number, which cannot not contain decimals/fractions. ''Ex:'' 10

* '''float''': A JSON number that can have a decimal/fraction. ''Ex:'' 3.14

* '''long''': An integer value of arbitrary length, formatted as a JSON decimal string. ''Ex:'' "672300213144"

* '''time''': A JSON string containing an ISO 8601 formatted combined date and UTC time, with 3 decimal places of precision. ''Ex:'' "2013-10-21T13:28:06.419Z" (10/21/13 13:28:6.41)

* '''array''': A JSON array of JSON objects. ''Ex:'' {"firstName":"John", "lastName":"Doe"}

=Usage=

@@ Line 26: / Line 26: @@
 It is important to state that applications will always be served the ''newest'' version of a representation by default, so that new applications use the newest version. It is very important to explicitly state which version of a given representation you are relying on in order to ensure the continued functionality of your applications, especially if these rely on the structure of a particular version of the representation.
-You can specify which version of a representation(s) you'd like your application to deal with by using the '''Accept''' header to specify what version of a representation you want to receive and the '''Content-Type''' header to specify what version to send out.
+You can specify which version of a representation(s) you'd like your application to deal with by using the '''Accept''' header to specify what version of a representation you want to receive (used in HTTP GET requests) and the '''Content-Type''' header to specify what version to send out (used in HTTP POST and PUT requests). More information on these these headers can be found [http://en.wikipedia.org/wiki/List_of_HTTP_header_fields here].
+===Representations in Code===
+Representations are formatted as [http://www.json.org/ JSON] (JavaScript Object Notation) objects, containing name/value pairs, nested objects and arrays. Some name and value pairs are optional, and can be omitted by senders when not necessary. Other name/value pairs have default values assigned to them if a value is not explicitly assigned.
+There are special names used across all representations that have special significance, and thus can be relied on to be consistent across all versions of a given representation.
+* '''href''': Intended to be used as a URI to an external resource.
+* '''name''': Intended to be used as a localized, human-readable name for a given resource.
+* '''id''': Intended to be used as an identifier for a given resource, which is not human-readable.
+The values used in these representations can be of various JSON data types; these are described below.
+* '''string''': A JSON string. ''Ex:'' "John Doe"
+* '''number''': A JSON number - the equivalent of double precision floating point format in Java and other languages. ''Ex:'' 65.1231415
+* '''int''': A JSON number, which cannot not contain decimals/fractions. ''Ex:'' 10
+* '''float''': A JSON number that can have a decimal/fraction. ''Ex:'' 3.14
+* '''long''': An integer value of arbitrary length, formatted as a JSON decimal string. ''Ex:'' "672300213144"
+* '''time''': A JSON string containing an ISO 8601 formatted combined date and UTC time, with 3 decimal places of precision. ''Ex:'' "2013-10-21T13:28:06.419Z" (10/21/13 13:28:6.41)
+* '''array''': A JSON array of JSON objects. ''Ex:'' {"firstName":"John", "lastName":"Doe"}
 =Usage=