I'd like some feedback
Arlo Belshee
We’re currently designing a new “lightweight Json” format for OData. I’ve mentioned it in some previous threads.
Our team just put up three experimental sample services. I would love to get design feedback from anyone on this list.
http://services.odata.org/Experimental/Northwind/Northwind.svc/?$format=json
http://services.odata.org/Experimental/OData/OData.svc/?$format=json
http://services.odata.org/Experimental/(S(readwrite))/OData/OData.svc/?$format=json
At this point, the design is still semi-fluid. We’ve implemented a bunch and thought through a bunch of concerns. But we are still tweaking the design as more concerns arise. So please highlight concerns. My goal is not to defend this design or argue that others should use it (although I do like it). Instead, I want to hear as much feedback as I can before we lock things down in a protocol spec.
All 3 services support $format=json or an accept header to request Json; they otherwise continue to default to Atom (for back-compat with older clients). The new lightweight Json format is the default Json format. You can request the old “Verbose Json” format with Accept: application/json;odata=verbose.
Our new format is an attempt to remove all of the metadata from our responses except when absolutely necessary. We assume that the clients can parse the $metadata resource; each resource includes a reference into the applicable part of the $metadata resource. The specific response includes metadata only when that response differs from the template defined in $metadata.
What do you think?
Arlo Belshee
Sr. Program Manager, OData, Microsoft
Mike Schinkel
I would love to get design feedback from anyone on this list.
...
What do you think?
Thanks for posting. Looking at it I'm not sure what it represents; is this the $metadata? Can you clarify?Also, stupid question probably but can I assume that I could write my URL like this:
To be equivalent to your URL here?
sune jakobsson
Arlo Belshee
These URLs are the service URLs (with a format query parameter to specify the desired response format). They are full OData services; you can do everything described in http://www.odata.org/media/30002/OData%20URL%20Conventions.html . But here are the basics.
All the following URLs are relative to the service root.
/ is the service doc. This describes all the resource sets available in the service.
/$metadata is the metadata. This describes the entire domain model (all types, relations between them, etc).
/<ResourceSetName>/ is a resource set. This allows read (or CRUD for the r/w service) access to all resources in that set.
/<ResourceSetName>(Key) is a single resource, identified by key.
/<ResourceSetName>(Key)/Property is a property on a resource. This can be used for primitive properties or for relationships. For a relationship, it returns the one or many related resources.
/AnyPath?$filter=<filter expression> allows filtering any set of resources.
/AnyPath?$orderby=<order expression> allows sorting any set of resources.
/AnyPath?$select=<set of properties> allows projection / partial queries. It returns only the properties that you ask for.
/AnyPath?$expand=<set of paths> allows inline expansion of related resources. The client can, for example, ask for customers with their orders expanded inline.
All of the above are composable. To get specific URLs, refer to the model. It states all the resource sets, types, property names, relation cardinality, and all the rest. It will also (but does not yet) include template construction rules that state all of the above conventions.
Here’s a complicated example that uses a bunch of these. It means “for this particular customer, fetch me all the orders that have a freight charge over $30. Please inline expand all the details for each order and sort them by shipped date, descending. Give me the results in Json.”
Constructing these is easy for programs but finicky for humans. Unfortunately, we haven’t updated the client helper tools yet to support the new format. This is an early design review, after all. So while this service is enough to play with and give design feedback, it certainly is not ready for prime time.
I hope this helps you play with it a bit.
Arlo