The following table is the set of query parameters defined by EDAA specification:
| Parameter | Meaning |
|---|---|
| page and per_page |
Pagination related |
| alt |
Alternative format of the resource representation (eg atom or JSON) |
| fields |
Specify the subset of fields (properties) of the resource that should be returned in the response (like SELECT in SQL) |
| expand |
Augment relationship representations with an in line feed of related resources |
| orderby |
comma separated list of properties the response should be sorted on. The response MUST present an atom:feed with the entries sorted by the values of the indicated fields (like ORDERBY in SQL) |
| filter |
simple boolean predicate expression to describe a filter, or subset, of the resources to return in a GET operation (like WHERE in SQL). |
| languages |
a string, in the format defined for http Accept-Languages header, containing a comma separated list of languages/locales (with quality weightings) that expresses the consumer's preference for localizing responses. |
| URI Pattern | page | per_page | alt | fields | expand | orderby | filter | languages |
|---|---|---|---|---|---|---|---|---|
| /types | Y | Y | Y | Y | Y | Y | ||
| types/{typeName} | Y | Y | ||||||
| /types/{typeName}/hierarchy | Y | Y | Y | Y | ||||
| /types/{typeName}/PR_Create | Y | Y | ||||||
| /types/{typeName}/instances | Y | Y | Y | Y | Y | Y | Y | Y |
| /instances | Y | Y | Y | Y | Y | Y | Y | |
| /instances/{id} | Y | Y | Y | Y | ||||
| /instances/{id}/relationships | Y | Y | Y | |||||
| /instances/{id}/relationships/{relName} | Y | Y | Y | Y | Y | Y | Y | Y |
Note, query parameters can be combined in a single request, for example:
GET /types/vCenter/instancespage=1&per_page=20&alt=atom&fields=displayName,id,connectionStatus&orderby=id&filter=connectionStatus%20eq%20DOWN
may be an appropriate (but complicated) request.
Note also that filter and orderby affect the interpretation of page because those filter changes which atom:entry elements are included in the "conceptual" atom:feed over which the request operations and orderby changes the order in which those atom:entry elements appear.
page and per_page
These query parameters define a "chunking" or "paging" view over a large collection of resources in an atom:feed.
An atom:feed is really just a collection of atom:entry elements, potentially a large number of them, conceptually an infinite number. The page and per_page query parameters work together to define a sequence of "chunks" called "pages" over this collection of atom:entries, each page containing at most the number of atom:entry elements as defined by per_page.
GET /{URL to conceptual feed}per_page=4&page=2
<atom:feed> <atom:entry>E <atom:entry>F <atom:entry>G <atom:entry
GET /{URL to conceptual feed}per_page=12&page=2
<atom:feed> <atom:entry>M <atom:entry>N <atom:entry>O <atom:entry>P </atom:feed>
Note that the two queries return different responses. Note also, in the second response that even though per_page=12 it did not guarantee there would be 12 atom:entry elements in the response.
Both page and per_page have integer values. If a value of page or per_page is not an integer, the EDAA MUST respond with an http error code 400 (bad request).
It is possible to specify ridiculous values of per_page. If per_page is not specified in the URL, or the value of per_page is less than 1, the EDAA implementation will substitute some default value of per_page, usually 20). If the value of per_page is some huge integer, like 10000, that exceeds the size of the "conceptual" atom:feed, then the request is accepted and 1 page containing the entire atom:feed is returned. For large values of per_page, the response time of the query and the processing requirements on the client and server may be large. It is not recommended that the client use large values of per_page unless they are prepared to wait for some time to receive the response and are prepared to consume/process a large response.
The values of page are a bit more constrained. If page is not specified in the URL, or the value of page is less than or equal to 1, then the first page (page=1) is used as the default value. If the value of page exceeds the number of pages in the conceptual feed, an error response is returned with http code 400 (bad request).
It should be noted that the semantics of paging is altered by the filter and orderby query parameters. If two queries are exactly the same, except for the value of orderby, then the response from each query will represent different orderings of the atom:entry elements in the "conceptual" atom:feed and therefore the contents of page=1 will likely be different between the two queries. Similarly, filter changes which atom:entry elements are in the "conceptual" atom:feed and will therefore change which atom:entry elements appear in any of the pages.
Interpretation by URI Pattern
| URI Pattern | Applicable? | Comments |
|---|---|---|
| /types | Yes | "conceptual" atom:feed is all the type resources known to the EDAA |
| /types/{typeName} | No | Response is a single (type) resource, no "conceptual" atom:feed is associated with the response. |
| /types/{typeName}/hierarchy | Yes | "conceptual" atom:feed is all the type resources within the type hierarchy of the type identified by {typeName} |
| /types/{typeName}/PR_Create | No | Response is a single (type) resource, no "conceptual" atom:feed is associated with the response. |
| /types/{typeName}/instances | Yes | "conceptual" atom:feed is all the instance resources of the type identified by {typeName} |
| /instances | Yes | "conceptual" atom:feed is all the instance resources known to the EDAA |
| /instances/{id} | No | Response is a single instance resource, no "conceptual" atom:feed is associated with the response. |
| /instances/{id}/relationships | No | Response is a single instances resource, no "conceptual" atom:feed is associated with the response. |
| /instances/{id}/relationships/{relName} | Yes | "conceptual" atom:feed is all the instance resources related to the resource identified by {id} through the relationship named {relName} |
alt
This query parameter allows a URL-level mechanism to control which format (Atom/XML or JSON) is used to serialize the resource representation in response to the request.
This query parameter is a convenience mechanism, useful for experimenting in a browser window. The functionality is duplicated with Content Negotiation in EDAA using the http Accept: header to specify consumer preference of format. It is preferred that the consumer use http Accept: headers to express format preference.
The range of value for alt is a string enumeration. Currently the only valid values of alt are "atom" and "json". More values may be added to this enumeration in the future, as additional formats are supported by EDAA (such as, perhaps csv for a "comma separated variable" serialization). If an invalid value of alt is specified in a URL, the EDAA MUST respond with an error, http code 400 (bad request).
Note, not all EDAA implementations are expected to support both Atom/XML and JSON serialization formats. Ideally, an EDAA should support both, but it is not strictly required. If a consumer specifies a value of alt that is valid, but not one of the serialization formats supported by the EDAA (for example the consumer uses alt=json on an EDAA that supports only Atom/XML), then the EDAA MUST respond with an error, http code 400 (bad request).
If no alt is specified in the URL, the EDAA implementation is free to choose which supported serialization format to use in the response.
As mentioned previously, the consumer can express serialization format preference using alt or an http Accept: header. In the case where the consumer uses both approaches, AND the approaches conflict (eg alt="atom" and the http Accept: specifies JSON), then the EDAA MUST return an error, 406 (not acceptable).
If a valid value of alt is specified in the URL, there is no conflict with an http Accept: header in the request and the corresponding serialization format is supported by the EDAA, then the EDAA MUST format the response to the request using the serialization format specified in alt.
For the value of alt=json, the serialization of the response is governed by the JSON conventions in EDAA also the rules to represent type resources and instance resources specified in EDAA.
If no value of alt is given in the URL and no Content type is specified in an http Accept: header, then the EDAA is free to choose which of serialization format to use for the response. If the EDAA supports alt=atom, it MUST use that as the default.
Interpretation by URI Pattern
The alt query parameter may appear on any URI pattern specified in EDAA.
fields
The idea of a fields query parameter is to allow the consumer to specify partial representations of the resource to be returned in responses. This provides a more succinct and fit for purpose representation to be specified by consumers, and avoids the overhead of server-side and client-side processing of attributes and relationships that are not of interest to the consumer.
With the fields query parameter, the consumer specifies a comma separated list of attribute names and relationship names. The resource representation(s) returned in the response will contain only those attributes and relationships specified in the fields query parameter.
... <vsc:typeName namespace="http://schemas.emc.com/msa/uim/1.0">vCenter</vsc:typeName> <atom:link rel="http://schemas.emc.com/msa/common/reln/PR_Create" href="http://localhost:8080/slm/msa/types/vCenter/PR_Create"/> <atom:link rel="self" href="http://localhost:8080/slm/msa/types/vCenter"/> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">displayName</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">ipAddress</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:long" minOccurs="1" maxOccurs="1">id</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">name</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">description</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">vCenterVersion</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">userName</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">port</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">password</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">connectionStatus</vsc:attribute> <vsc:attribute type="http://www.w3.org/2001/XMLSchema-datatypes:string" minOccurs="1" maxOccurs="1">dataCentersList</vsc:attribute> <vsc:relationship relType="vCenterDatacenter" type="http://schemas.emc.com/msa/common/contains" minOccurs="1" maxOccurs="unbounded" description="List of Datacenters">Datacenters</vsc:relationship> ...
GET /types/vCenter/instancesfields=displayName,id,Datacenters
<?xml version="1.0" encoding="UTF-8"?> <feed xmlns:atom="http://www.w3.org/2005/Atom" xmlns="http://www.w3.org/2005/Atom" xmlns:vsc="http://schemas.emc.com/vs-xml/namespace/Common/1.0"> <title>/slm/msa/types/vCenter/instances</title> <updated>2011-05-24T08:20:55-05:00</updated> <author><name>msa framework</name></author> <id>5aabb570-340e-4e6d-adaf-91c38c5e743a</id> <link rel="self" href="http://localhost:8080/slm/msa/types/vCenter/instancesfields=displayName,id,Datacenters"/> <entry xmlns:gd='http://schemas.google.com/g/2005' xmlns:atom="http://www.w3.org/2005/Atom" gd:etag='“ADEEFO42drp7tKA7QxRDBIL."'> <atom:title type='text'>vCenter - lglan195</atom:title> <atom:id>http://localhost:8080/slm/msa/instances/vCenter::1</atom:id> <atom:updated>2011-05-24T08:20:55-05:00</atom:updated> <atom:link rel='self' href='http://localhost:8080/slm/msa/instances/vCenter::1fields=displayName,id,Datacenters' /> <atom:link rel='alternate' href='http://localhost:8080/slm/msa/instances/vCenter::1' /> <atom:content type='application/xml'> <inst:vCenter xmlns:atom='http://www.w3.org/2005/Atom' xmlns:vsc='http://schemas.emc.com/vs-xml/namespace/Common/1.0' xmlns:inst='http://schemas.emc.com/msa/uim/1.0'> <inst:displayName>lglan195</inst:displayName> <inst:id>1</inst:id> <atom:link rel='http://schemas.emc.com/msa/uim/1.0/vCenter/relationship/Datacenters' href='http://localhost:8080/slm/msa/instances/vCenter::1/relationships/Datacenters' /> </inst:vCenter> </atom:content> <entry> <atom:title type='text'>vCenter - matt 111</title> <atom:content type='application/xml'> <inst:vCenter ... <inst:displayName>matt 111</inst:displayName> <inst:id>9</inst:id> <atom:link rel='http://schemas.emc.com/msa/uim/1.0/vCenter/relationship/Datacenters' href='http://localhost:8080/slm/msa/instances/vCenter::9/relationships/Datacenters' /> </inst:vCenter> </atom:content> </entry> ... etc. for every vCenter instance </feed>
Note how the representation of each vCenter resource is a partial representation, containing only the properties of the resource specified in fields.
When an EDAA is processing a partial representation formed by a fields query parameter, the EDAA reduces the content of each representation to include only those attributes and relationships whose name appears in the list of names in the value of fields. If a resource does not have an attribute or relationship corresponding to one of the names in the list, that name is silently ignored. The net result is that the representation of any resource appearing in the response contains only the properties named in the fields query parameter. It is possible that a resource type could have an attribute and a relationship with the same name. In this case, if a name is specified in the value of fields that corresponds to both an attribute and a relationship then the resulting partial representation will contain both properties.
Interpretation by URI Pattern
| URI Pattern | Applicable? | Comments |
|---|---|---|
| /types | No | |
| /types/{typeName} | No | |
| /types/{typeName}/hierarchy | No | |
| /types/{typeName}/PR_Create | No | |
| /types/{typeName}/instances | Yes | Since all the resources in the response are of the same type, then this use of fields is very useful to generate focused partial representations. Since a large number of resources may be returned in the response, specifying a very compact representation for each resource can be extremely beneficial to request/response latency and client and server side resource use. |
| /instances | Yes | Not terribly useful because there will be few property names that are shared amongst all types of resource instance. Many of the representations will be empty, even for common property names like "name" or "displayName" or "id". However, the partial representation filter implied by fields will be applied to each resource in the response. |
| /instances/{id} | Yes | Questionably useful, given that atom:feeds containing a single resource, as expected from this URI pattern, aren't often very large, and therefore the partial representation technique really doesn't reduce the response size significantly from the full representation of the resource. |
| /instances/{id}/relationships | Yes | As with /instances/{id}, above |
| /instances/{id}/relationships/{relName} | Yes | Applies to the related resource representations contained in the response. Since this request is focused on a single relationship, the resources in the response are all of the same type, and therefore a reasonable partial representation can be specified by fields. |
expand
The idea with the expand query parameter is to give the consumer some control of the representation of relationships that appear in a resource's representation. The consumer uses expand on a GET operation to specify which relationships should be expanded. An expanded relationship augments the normal relationship representation, an atom:link element, with a child (or inline) feed of related resources. If a consumer wants to avoid having to do an additional GET operation to retrieve the resources related to a particular resource, it would use the expand query parameter to add additional information about related resources across one or more relationships.
Note, the in line feed of related resources may also be paginated, at the control of the server. The use of page and per_page does not compose with expand. The page and per_page does not alter the pagination properties of the in-line feeds. The pagination of in-line feeds is under the control of the server.
Interpretation by URI Pattern
| URI Pattern | Applicable? | Comments |
|---|---|---|
| /types | No | |
| /types/{typeName} | No | |
| /types/{typeName}/hierarchy | No | |
| /types/{typeName}/PR_Create | No | |
| /types/{typeName}/instances | Yes | Since all the resources in the response are of the same type, then this use of expand is very useful to generate consistency in the way relationships are represented in the response. Since a large number of resources may be returned in the response, specifying expand=* or a large list of named relationships in the value of expand may cause the response to become very large. |
| /instances | Yes | Although expand applies to this URI pattern, the heterogeneity of resource type returned means that for many resources, the relationships named in the query parameter may not match relationships defined for many instances. It is not a problem if a relationship named in the expand does not appear in any given resource, it simply means that a relationship with that name is unavailable to expand with an in-line feed. |
| /instances/{id} | Yes | Most useful to avoid round trip of an additional GET operation to retrieve a feed of related resources, in addition, because this operation returns a singleton, the chances of the response becoming very large is not as great as with URIs that return collections, like /types/{typeName}/instances |
| /instances/{id}/relationships | No | |
| /instances/{id}/relationships/{relName} | Yes | Expansion of relationship representations applies to the representation of the related resources |
orderby
The orderby query parameter allows the consumer to control the order of appearance of atom:entries within a "conceptual feed".
<atom:feed> <atom:entry> <attr1>A <attr2>10 <atom:entry> <attr1>B <attr2>9 <atom:entry> <attr1>C <attr2>8 <atom:entry> <attr1>D <attr2>7 <atom:entry> <attr1>E <attr2>6 <atom:entry> <attr1>F <attr2>5 </atom:feed>
GET /{URL to conceptual feed}orderby=attr1%20DESC
<atom:feed> <atom:entry> <attr1>F <attr2>5 <atom:entry> <attr1>E <attr2>6 <atom:entry> <attr1>D <attr2>7 <atom:entry> <attr1>C <attr2>8 <atom:entry> <attr1>B <attr2>9 <atom:entry> <attr1>A <attr2>10 </atom:feed>
Note that the atom:entries appear in sorted order by the value of the "attr1" property in descending order.
The orderby query parameter takes as value a comma separated list of "sort specifiers". Each "sort specifier" is composed of a string name followed optionally by a direction indicator. The string name identifies an attribute name property of a resource. The direction indicator is either "ASC" or "DESC". If there is no direction indicator within a "sort specifier", the default value is "ASC".
Because the value of orderby is a comma separated list of these sort specifiers, it is possible to specify nested collating sequences.
For example, orderby=attr1%20ASC,%20attr2%20DESC,attr3,attr4, (note the URL encoding of the whitespace) would cause the atom:entry elements to be first sorted by the value of the resource property "attr1" (in ascending sequence) and within that, sorted by the value of att2 (in descending sequence), and within that sorted by attr3 and then by attr4.
If a "sort specifier" contains a "direction indicator" with a value other than "ASC" or "DESC" (or their lowercase equivalents) then the EDAA must return an error response, with http code 400 (bad request).
If a "sort specifier" contains a name of an attribute that does not appear within a given resource, then, for the purposes of sorting, value should be considered NULL, and the atom:entry corresponding to that resource should appear in the collation sequence as if the resource represented by the atom:entry had an attribute with the given name and the value of that attribute was NULL.
If an orderby query parameter is not specified in a request, the EDAA implementation is free to return the atom:entry elements in whatever sequence it chooses, but it MUST be consistent in the collation sequence applied to atom:entry elements in absence of an orderby query parameter.
The orderby query parameter is very similar to a SQL "ORDERBY" clause.
Interpretation by URI Pattern
| URI Pattern | Applicable? | Comments |
|---|---|---|
| /types | Yes* | The attribute model is fixed. The set of attributes upon which types feeds can be sorted is "typeName". |
| /types/{typeName} | No | |
| /types/{typeName}/hierarchy | No | |
| /types/{typeName}/PR_Create | No | |
| /types/{typeName}/instances | Yes | Since all the resources in the response are of the same type, it is easy for the consumer to specify useful sorting order with orderby. |
| /instances | Yes | Not terribly useful because there will be few property names that are shared amongst all types of resource instance, for any value of orderby, there will be many resources that do not contain one or more of the attributes specified in the "sort specifiers" defined in the value of orderby, resulting in many atom:entries being sorted by NULL values for those attributes. |
| /instances/{id} | No | |
| /instances/{id}/relationships | No | As with /instances/{id}, above |
| /instances/{id}/relationships/{relName} | Yes | Applies to the related resource representations contained in the response. Since this request is focused on a single relationship, the resources in the response are all of the same type, and therefore a reasonable sorting of those atom:entries can be specified by orderby. |
filter
The filter query parameter has functionaly analogous to a SQL WHERE clause. The idea with filter is to allow the consumer to specify a filter expression, composed of boolean predicates that are applied against potential resources and acting as a filter so that only those resources that cause the filter expression to evaluate true are represented in the response.
<atom:feed> <atom:entry> <attr1>A <attr2>10 <atom:entry> <attr1>B <attr2>9 <atom:entry> <attr1>C <attr2>8 <atom:entry> <attr1>D <attr2>7 <atom:entry> <attr1>E <attr2>6 <atom:entry> <attr1>F <attr2>5 </atom:feed>
GET /{URL to conceptual feed}filter=attr2 LT 8
<atom:feed> <atom:entry> <attr1>D <attr2>7 <atom:entry> <attr1>E <attr2>6 <atom:entry> <attr1>F <attr2>5 </atom:feed>
GET /{URL to conceptual feed}filter=attr2%20LT%208
This mechanism is useful, for example, in building UIs that allow the end-user to choose expression(s) on properties to be displayed in a table. Smarts, for example, provides a mechanism to filter a table of Alert resources by providing UI widgets allowing the user to form boolean expressions on any/all columns. An example screen shot is shown below:
With the filter query parm feature of EDAA, the UI shown above could form predicates and use the server to do the resource filtering.
If the consumer submits a request containing a filter query parameter with value that does not conform to the filter expressions described below, then the EDAA implementation MUST reject the request, returning an http error code 400 (bad request).
Filter Expressions
The value of a filter query parameter is a filter expression as described in this section.
... <link href=".../types/FileServer" rel="self"></link> ... <entry><title type="text">FileServer</title> ... <content type="application/xml"> <type:Type xmlns:type="http://schemas.emc.com/vs-xml/namespace/Common/1.0" xmlns:atom="http://www.w3.org/2005/Atom"> <type:typeName namespace="http://schemas.emc.com/vs-xml/namespace/ip/1.0">FileServer</type:typeName> ... <type:attribute type="xs:string" minOccurs="0" maxOccurs="1">IsManaged</type:attribute> ...
GET /types/FileServer/instancesfilter=IsManaged eq true
- have @type as a simple type (eg xs:string, etc.), and
- have @maxOccurs as "1"
can participate in a filter expression.
filter_expr ::= bool_expr | filter_expr 'or' bool_expr bool_expr ::= pexpr | bool_expr 'and' pexpr pexpr ::= bool_pred | ‘(‘ filter_expr ‘)‘ bool_pred ::= simple_pred | 'not' pexpr simple_pred ::= property_name rel_op term | property_name ‘in’ ‘(‘ in_list ‘)’ | property_name 'lk' like_term rel_op ::= 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' //equals, not equals, greater than, greater than or equal, less than and less than or equal to in_list ::= string_lit | in_list ‘,’ string_lit like_term ::= string_lit The “like_term” is a string literal used with the lk operator; it can include a leading or trailing % wildcard to match zero or more characters. % is encoded in a URI as “%25”. and property_name is a string literal corresponding to an attribute property of a resource type meeting the constraints described above and term is a valid string serialization of a value within the range of the simple type associated with the property defined by the property_name in the simple_pred expression. See terms below.
filter expression terms
Filter expressions are built by combining simple predicates of the form "property name" "operator" "term". The set of valid values for "property name" are defined by the resource model associated with the EDAA implementation. The set of operators is defined above ('eq' , 'ne' , 'gt' , 'ge' , 'lt' , 'le', 'in' , 'lk' ). The valid value for "term" depends somewhat on the operator.
Terms are values with simple type. In the filter syntax, we use the simple syntax for primitive terms defined by JSON . Specifically, a term can be a string, number, or any of the following literal values: true, false, null.
A string is defined by JSON as:
A number is defined by JSON as:
Dates, date/time and timestamps should be represented syntactically using ISO 8601.
filter=foo in ("baz", "bar", "blee")would evaluate to true.
filter=foo lk "%bar%"would evaluate to true.
filter expression operator precedence
GET /types/T/instancesfilter=p1 eq "a" AND p2 eq "b" AND (p3 eq 8 OR p3 eq 9)
Note the use of the parentheses for the expression predicate involving p3. The AND expression has higher precedence than OR. Had the consumer not used parenthesis here, the filter would not return the desired subset of instances.
| Level | Operators |
|---|---|
| 1 | expressions in parentheses (pexpr) |
| 2 | 'eq' , 'ne' , 'gt' , 'ge' , 'lt' , 'le', 'in' , 'lk' |
| 3 | NOT |
| 4 | AND |
| 5 | OR |
-
GET /types/T/instancesfilter=p1 eq "a" AND p2 eq "b" AND p3 eq 8 OR p3 eq 9
-
GET /types/T/instancesfilter=(p1 eq "a" AND p2 eq "b" AND p3 eq 8) OR p3 eq 9
-
GET /types/T/instancesfilter=p1 eq "a" AND p2 eq "b" AND (p3 eq 8 OR p3 eq 9)
The first two requests produce the same subset of instances, whereas the third request produces a different subset.
Missing Properties and Filter Expressions
Note that some resources may not contain values for properties defined in their type. For example, if a property is declared as minOccurs=0, any given instance of that type may or may not contain a value. What is the semantic of a filter expression referencing that property?
<vsc:Type ... <vsc:typeName ...>T</vsc:typeName> ... <vsc:attribute minOccurs="1" ...>p1</vsc:attribute> <vsc:attribute minOccurs="0" ...>p2</vsc:attribute> ... </vsc:Type>
A GET on /types/T/instances may result in a collection that contains resources of type "T", some of which may not have a value for property p2.
A GET on /types/T/instancesfilter=p2 eq "foo" poses an interesting challenge. For those instances that contain a value for p2, the semantic is clear, evaluate the predicate against the value of p2 and include that instance in the response collection if the predicate evaluates to true. For an instance that does not contain a value for p2, the predicate MUST evaluate to false.
In general, if a filter expression contains a reference to a property not present in a given instance, that predicate MUST evaluate to false.
Interpretation by URI Pattern
| URI Pattern | Applicable? | Comments |
|---|---|---|
| /types | Yes* | The property model is fixed. The set of properties upon which types feeds can be filtered is "typeName". |
| /types/{typeName} | No | |
| /types/{typeName}/hierarchy | No | |
| /types/{typeName}/PR_Create | No | |
| /types/{typeName}/instances | Yes | Since all the resources in the response are of the same type, it is easy for the consumer to specify useful filter expressions. |
| /instances | No | Not terribly useful because there will be few property names that are shared amongst all types of resource instance, for any filter expression appearing in filter will, for many resources, result in an illegal filter expression, thereby making the probability of having a request actually return successfully very small. |
| /instances/{id} | No | |
| /instances/{id}/relationships | No | As with /instances/{id}, above |
| /instances/{id}/relationships/{relName} | Yes | Applies to the related resource representations contained in the response. Since this request is focused on a single relationship, the resources in the response are all of the same type, and therefore a reasonable filter expression can be formed. |
languages
This query parameter allows a URL-level mechanism to control which language/locale the consumer would prefer the EDAA to use when localizing responses.
This query parameter is a convenience mechanism, useful for experimenting in a browser window or when the client technology (such as Flex/Flash) makes it difficult to manipulate http headers. The functionality is duplicated with Language Negotiation in EDAA using the http Accept-Language: header to specify consumer preference of localization. It is preferred that the consumer use http Accept-Language: headers to express language/locale preference.
The range of value for languages is a string. The format of the string is exactly that specified for http Accept-Language header. The value of languages is a comma separated set of language/locale tags with an optional quality (preference) value. For example, languages="da, en-gb;q=0.8, en;q=0.7", expresses the consumer's preference to have responses localized to Danish, and if that is not possible, will accept responses localized to British English, or (with slightly less preference) any English dialect.
If an invalid value of languages is specified in a URL, the EDAA MUST respond with an error, http code 400 (bad request).
If none of the acceptable languages specified by the consumer are supported by the EDAA, then the EDAA MUST respond with an error, http code 406 (Not Acceptable).
As mentioned previously, the consumer can express localization preference using languages or an http Accept-Languages: header. In the case where the consumer uses both approaches, AND the approaches conflict (eg there is no language/locale that appears in both lists of preference), then the EDAA MUST return an error, 406 (not acceptable).
If no form of localization preference is expressed by the consumer, an EDAA implementation is free to choose which language/locale to use.
If a valid value of languages is specified in the URL, there is no conflict with an http Accept-Language: header in the request and at least one language/locale is supported by the EDAA, then the EDAA MUST format the response to the request using a supported language/locale format specified as being most preferred by the consumer.
If no form of localization preference is expressed by the consumer, an EDAA implementation is free to choose which language/locale to use.
Interpretation by URI Pattern
The languages query parameter may appear on any URI pattern specified in EDAA.
