for a discussion around payload formats used by Astoria.<\/FONT><\/P>\n <\/FONT><\/P>\nIn general, Astoria takes a conceptual model expressed in terms of entities in an EDM schema and surfaces data that follows that model over an HTTP interface, representing entities as resources and associations between entities as links. The URI interface needs to provide a rich yet simple way of addressing those resources.<\/FONT><\/P>\n <\/FONT><\/P>\nThe URI format in Astoria has a few specific goals:<\/FONT><\/P>\na)<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Provide a mechanism to point to every resource or member of a resource in the system.<\/B> That is, every piece of data is addressable, and the URI used to address it needs to be derivable from the service metadata which describes the conceptual model of the system<\/FONT><\/FONT><\/P>\nb)<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Allow for simple queries to be formulated.<\/B> That is, instead of pointing to a particular resource, allow URIs that express filtered sets of resources satisfying certain criteria<\/FONT><\/FONT><\/P>\nc)<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Support manipulating the presentation of results.<\/B> This includes things such as sorting resources, paging over them and expanding related resources.<\/FONT><\/FONT><\/P>\n<\/FONT> <\/P>\nThis \u201cpart I\u201d write up focuses on item a) above; pointing to resources and their members. We will discuss b) and c) in future blog posts<\/FONT><\/P>\n<\/FONT> <\/P>\nNOTE: the following descriptions use EDM terminology and constructs. <\/SPAN>Regardless of the underlying data access layer (Entity Framework, Custom LINQ provider, etc) an Astoria service is exposing, the service is described using an EDM schema, so this description applies equally to any data source. <\/SPAN>In addition, typical REST verbiage (as is done above) refers to items pointed to by URIs as resources. <\/SPAN>In the remainder of this write up the term \u2018entity\u2019 should be interpreted as a synonym for \u2018resource\u2019.<\/FONT><\/P>\n <\/FONT><\/P>\n <\/FONT><\/P>\nStarting from the root<\/FONT><\/FONT><\/B><\/P>\nAt the root of the service we are thinking of carrying the behavior of the CTP forward and putting all of the resource sets<\/I>, which are simply the list of entity sets we find in the EDM schema. These are addressed by name, separated by a forward-slash (\u201c\/\u201d) from the service root URI. (e.g. \u2026\/northwind.svc\/Customers, where \u201cCustomers\u201d is a resource container).<\/FONT><\/P>\n <\/FONT><\/P>\nA detail: In an EDM schema an entity set is contained within a single entity container and there may be multiple entity containers in the schema. If that\u2019s the case, to access non-default containers, the names need to be container-qualified (e.g. \u201c\/NorthwindContainer.Customers\u201d). The default one *cannot<\/B>* be qualified, to avoid introducing a redundant way of getting to it.<\/FONT><\/P>\n <\/FONT><\/P>\nPointing to a particular entity<\/FONT><\/FONT><\/B><\/P>\nEvery entity in an EDM schema has a key which consists of one or more of the properties in the entity. An entity key is unique within the containing entity set, so to identify an entity with a URI we need to include at least the entity-set and the key values. <\/FONT><\/P>\n <\/FONT><\/P>\n\n–Location of keys<\/FONT><\/FONT><\/B><\/P>\nThe key value could go before or after the question mark. That is, the URI could be built by adding a query parameter after the URI question mark as in:<\/FONT><\/P>\n <\/FONT><\/P>\n\u2026\/northwind.svc\/Customers?key=23<\/FONT><\/P>\n <\/FONT><\/P>\nOr we could consider the entity-set-plus-value construct part of the URI namespace of the service and write it as<\/FONT><\/P>\n <\/FONT><\/P>\n\u2026\/northwind.svc\/Customers(23)<\/FONT><\/P>\n <\/FONT><\/P>\nWe prefer the second approach with the entity-sets and keys form a URI namespace and there is no query parameter required. <\/SPAN>One of the reasons for leaning towards the second approach is that it makes it explicit which entity set the key is associated with, especially when the URI path becomes quite long. <\/FONT><\/P>\n <\/FONT><\/P>\n–a bit of syntax<\/FONT><\/FONT><\/B><\/P>\nNow, assuming we go with that approach, there is now the question of the syntax. The May 2007 CTP used values in square-brackets (e.g. \u201c\u2026\/Customers[ALFKI]\u201d). We got \u201cgenerous\u201d feedback saying that square-brackets were a bad choice. <\/FONT><\/P>\n <\/FONT><\/P>\nThe approach we are currently thinking to take is to attach the key directly after the entity set name and using the \u2018!\u2019 character as the separator (e.g. \u2026\/Customers!23 ). <\/SPAN>That said, as per our last \u201cdesign\u201d posting on formats, we are looking to support the Web3S format. <\/SPAN>Web3S has a more flexible data model in that it allows heterogeneous sets while an Astoria server supports homogenous sets. <\/SPAN>To enable interoperability between any servers implementing Web3S and an Astoria server a URI scheme flexible enough to address heterogeneous sets is required. <\/SPAN> <\/SPAN>Therefore, we are thinking to expand on our current approach and allow a \u201cfull\u201d form of URI and a \u201ccompressed\u201d form, where the full form supports heterogeneous sets and the compressed form can be used as a shorthand notation when the set being addressed is on an Astoria server and is thus homogenous. <\/SPAN>For example:<\/FONT><\/P>\n <\/FONT><\/P>\n\u201cFull\u201d form: \u2026\/Customers\/Customer(123) would identify the instance 123 of type Customer within the Customers set. <\/SPAN><\/FONT><\/FONT><\/P>\n <\/FONT><\/P>\n\u201cCompressed\u201d form: \u2026\/Customers!123 would identify the same resource as above in Astoria because the \u2018Customer\u2019 type is implied since Astoria Servers support homogenous sets. <\/SPAN><\/FONT><\/FONT><\/P>\n <\/FONT><\/P>\n–composite keys<\/FONT><\/FONT><\/B><\/P>\nOne option would be to encode name\/value pairs, but that would result in verbose URIs and extra syntax to be invented. We are leaning toward a simple approach: we only use the values, separated by semicolon. The values are listed in the same order as they appear in the metadata document which describes the service. <\/SPAN>Metadata will be the topic of a future post, however, for now it\u2019s enough to say in the typical case the description of a service will be available by making a GET request to \u2026\/$metadata. <\/SPAN> <\/SPAN>The following is an example of a URI which contains a composite key:<\/FONT><\/P>\n <\/FONT><\/P>\n\u2026\/Customers!\u2019ALFKI\u2019,2<\/FONT><\/P>\n <\/FONT><\/P>\nSome folks love this, some hate it. The main concern from folks who hate it is readability: you cannot interpret the URI without the schema. Is that an issue? The alternate option of using name-value pairs is more explicit in this sense. We could have:<\/FONT><\/P>\n <\/FONT><\/P>\n\u2026\/Customers!CustomerID=’ALFKI’,Key=2<\/FONT><\/P>\n <\/FONT><\/P>\nThe single-key case would still not require the name, and given that most cases will be single-key cases, compactness won\u2019t suffer too much. An aspect of this that\u2019s both good and bad is the fact that by using names you can specify the values in different order. That\u2019s \u201chandy\u201d, but it means that these URIs are not useful for comparison as strings when trying to determine identity.<\/FONT><\/P>\n <\/FONT><\/P>\n— literal forms<\/FONT><\/FONT><\/B><\/P>\nUsing just literal values in a composite key doesn\u2019t really work, because now you cannot tell whether that\u2019s a 2-element key or a 1 element key that happens to have a comma in it. So we need to use proper literal forms for the values. We will need that when we want to express query expressions such as filter predicates anyway, so we may as well be consistent and use a single literal form everywhere.<\/FONT><\/P>\n <\/FONT><\/P>\nLiterals:<\/FONT><\/P>\n\u00b7<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Strings: a string surrounded by single-quotes, (e.g. ‘ALFKI’)<\/FONT><\/P>\n\u00b7<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Numbers: just the number, using US style (dot separates decimal digits)<\/FONT><\/P>\n\u00b7<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Dates: quoted as strings. Inside the string, use format described in RFC3339<\/FONT><\/P>\n\u00b7<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Guids: use the form <\/FONT>\u201cdddddddd-dddd-dddd-dddd-dddddddddddd\u201d<\/SPAN><\/P>\n\u00b7<\/FONT> <\/SPAN><\/SPAN><\/SPAN>Binary: \u201c0x\u201d followed by two hex digits per byte (e.g. 0x1AB4)<\/FONT><\/P>\n <\/FONT><\/P>\nSo the examples above would actually be, for single- and composite-key respectively:<\/FONT><\/P>\n <\/FONT><\/P>\n\u2026\/Customers(‘ALFKI’)<\/FONT><\/P>\n\u2026\/Customers(‘ALFKI’,2)<\/FONT><\/P>\n <\/FONT><\/P>\nProbably is a good idea to not<\/B> allow spaces, as it would help making sure that URIs that mean the same thing are easily comparable.<\/FONT><\/P>\n <\/FONT><\/P><\/BLOCKQUOTE>\n <\/FONT><\/P>\nAddressing members<\/FONT><\/FONT><\/B><\/P>\nTo address a member of an entity, simply append the member to a URI that points to the entity, separated by a forward-slash. For example, if Customers have a CompanyName property:<\/FONT><\/P>\n <\/FONT><\/P>\n\u2026\/Customers!’ALFKI’\/CompanyName<\/FONT><\/P>\n <\/FONT><\/P>\nNote that addressing a member like that would return the member appropriately wrapped to conform to the negotiated MIME type. For example, if using XML you\u2019d get the value wrapped in an XML element and annotated with the required namespaces and such.<\/FONT><\/P>\n <\/FONT><\/P>\nIf you want just the value with no wrappers, you can use the \/$value \u201cmagic member\u201d. For example:<\/FONT><\/P>\n <\/FONT><\/P>\n\u2026\/Customers(‘ALFKI’)\/CompanyName\/$value<\/FONT><\/P>\n <\/FONT><\/P>\nFor a string, this would just return the string (text\/plain) by default (same applies to all types but binary, which would return application\/octet-stream). The developer can customize this by annotating the schema and indicating which MIME type a given value should be treated as. That would allow for example a text field to store HTML or a binary field to store an image, and HTTP responses would include the proper MIME type for them.<\/FONT><\/P>\n <\/FONT><\/P>\nAssociation traversal<\/FONT><\/FONT><\/B><\/P>\nA special form of member access is when the member being accessed is actually a navigation property (a link in non EDM terms). Such a property can be considered a hard-link that resolves into the related entity (for associations that have a cardinality of 1 on the other end) or a set of entities (if the other end is \u201cmany\u201d).<\/FONT><\/P>\n <\/FONT><\/P>\n