RESTful ATHENA
Micah Frost
I've been reviewing the current resources provided by ATHENA-Tix, and want to bounce a few ideas off of the list.
Please refer to this wiki page: http://github.com/fracturedatlas/parakeet/wiki/Parakeet-Resources. Currently, the resources look something like this (if your mail reader has issues formatting this, I've posted it to github: http://gist.github.com/602034):
POST /tickets # Add a new ticket
GET /tickets?{key=value} # Get tickets with a certain value
GET /tickets/{id} # Get the specified ticket
DELETE /tickets/{id} # Delete the specified ticket
GET /tickets/{id}/props # Get the properties for a given ticket
DELETE /tickets/{id}/props/{name} # Get the value for a given ticket and property
GET /fields # Get all fields.
POST /fields # Create a new field.
GET /fields/{id} # Get the specified field.
DELETE /fields/{id} # Delete a field. Does this also out all instances of this field?
POST /fields/{id} # Add possible value to the field.
GET /fields/{id}/values # Get possible values for the given field.
Here is the design I am proposing:
GET /tickets # Get all (or some reasonable subset of) tickets.
POST /tickets # Add a new ticket.
GET /tickets/{id} # Get a given ticket.
DELETE /tickets/{id} # Delete a given ticket.
PUT /tickets/{id} # Update the details on a a given ticket.
GET /tickets/schema # Get the current schema for tickets.
HEAD /tickets/schema # Make small requests to get information like: "Has the schema changed?"
POST /tickets/schema/fields # Add a field to the schema.
GET /tickets/schema/fields/{id} # Get a given field.
DELETE /tickets/schema/fields/{id} # Delete a given field.
PUT /tickets/schema/fields/{id} # Update a given field.
GET /tickets/schema/fields/{id}/values # Get the acceptable values for a given field.
POST /tickets/schema/fields/{id}/values # Add an acceptable value for a given field.
GET /tickets/schema/fields/{id}/values/{value_id} # Get a specific value
PUT /tickets/schema/fields/{id}/values/{value_id} # Update a given value.
DELETE /tickets/schema/fields/{id}/values/{value_id} # Delete a given value.
Here's what the design buys us:
- A uniform interface that falls in line with currently accepted usage for the 4 HTTP verbs. POSTing to a collective resource adds one to the collection.
- Encapsulation of ATHENA logic surrounding the flexibility of the Ticket model. By flattening the Ticket into a single model without "props", the client is safe to assume the JSON returned describes the Ticket itself. A typical argument for returning a Ticket.props hash is to avoid naming collision with system names. Instead of letting such collisions dictate design, I would propose we use a prefixed underscore to indicate ATHENA-level properties. Then, users would not be allowed to submit field names that started with an underscore.
- When the client does need to ask about what a Ticket looks like, the client can GET the schema. From a relationship standpoint, Ticket has one Schema; Schema has many fields. Fields have many values. Modeling the system in this manner allows the client to check on the schema and make assumptions during run time.
The interface for a model's schema can and should be uniform across ATHENA components. This easily gives rise to abstractions like an AthenaModel class, which would know how to properly handle a flexible model served from ATHENA. If someone wanted to write a new component, and provided the proper interface, there is potential for savings on both the server and client side.
A final thought to consider: this also introduces the concept of multiple Schemas for a ticket. Down the road, this might be how ATHENA supports a wide variety of tickets.
Sorry for the small book. Please let me know what you think.
Micah
Adam Huttler
--
Visit: http://athena.fracturedatlas.org/tix
You received this email because you are subscribed to the "ATHENA Tix Developers" group on Google Groups.
To post, email: athena-t...@googlegroups.com
To unsubscribe, email: athena-tix-dev...@googlegroups.com
For more, visit: http://groups.google.com/group/athena-tix-devel?hl=en
Micah L. Frost
From the actual user's perspective, artful.ly can offer extension-based representations. Whether or not ATHENA can/should provide the same functionality is a different question.
Micah
----- Original Message -----
From: "Adam Huttler" <adam.h...@fracturedatlas.org>
To: athena-t...@googlegroups.com
Sent: Wednesday, September 29, 2010 9:15:31 AM
Subject: Re: [athena-tix-devel] RESTful ATHENA
Micah,
Is there any role for file extensions in this API? If we're committed to JSON-or-bust then it might not matter. But by supporting something like:
GET /tickets/{id}.json # Get the specified ticket in a JSON-encoded response
you open the door to eventually supporting:
GET /tickets/{id}.xml # Get the specified ticket in an XML formatted response
Again, not sure this matters, but could introduce some added flexibility.
-Adam
Hey all,
I've been reviewing the current resources provided by ATHENA-Tix, and want to bounce a few ideas off of the list.
Please refer to this wiki page: http://github.com/fracturedatlas/parakeet/wiki/Parakeet-Resources . Currently, the resources look something like this (if your mail reader has issues formatting this, I've posted it to github: http://gist.github.com/602034 ):
1. A uniform interface that falls in line with currently accepted usage for the 4 HTTP verbs. POSTing to a collective resource adds one to the collection.
2. Encapsulation of ATHENA logic surrounding the flexibility of the Ticket model. By flattening the Ticket into a single model without "props", the client is safe to assume the JSON returned describes the Ticket itself. A typical argument for returning a Ticket.props hash is to avoid naming collision with system names. Instead of letting such collisions dictate design, I would propose we use a prefixed underscore to indicate ATHENA-level properties. Then, users would not be allowed to submit field names that started with an underscore.
3. When the client does need to ask about what a Ticket looks like, the client can GET the schema. From a relationship standpoint, Ticket has one Schema; Schema has many fields. Fields have many values. Modeling the system in this manner allows the client to check on the schema and make assumptions during run time.
Gary Moore
We can still add XML later if there is demand from the users.
These two endpoints will behave the same:
GET /tickets/{id}.json
GET /tickets/{id}
Justin Karr
Micah,
I’m all for changing the architecture if it makes things better, but I don’t want to slow things down either.
POST-PUT:
We talked a lot about POST and PUT when we decided to break REST slightly by dropping PUT. I argued in favor of making it easier for client developers: one instruction to write, be it to add or to change. Am I crazy? Is ignoring PUT actually going to make things harder? How does this look from an application developer’s perspective? How important is this standard? I want ATHENA to be as standards-compliant as possible, and you’ll get the most support from me on changing this bit, provided we can make a decent argument for it and it doesn’t take a lot of time and resources to change.
SCHEMAS:
Under what scenario would we want multiple schemas for objects in a parakeet store like tickets? Does this help multi-tenancy (where multiple organizations are using the same ATHENA server)? Does this hurt or help searching across multiple companies’ tickets? Unless this is a big win for multi-tenancy (a big issue) and does not set back Fintan’s work on queries, I’m inclined to resist this.
PROPS as HASH:
Does having PROPS in a hash make things harder for client developers? Do we break standard practice by doing it this way? If not, this is the one I’m inclined to give the most push-back on as it is fairly intrinsic right now.
People outside the ATHENA core team: pipe up. I’d love your input on this.
Justin
--
Micah L. Frost
On the POST vs PUT front: the power of a RESTful interface is derived from the uniform interface provided to handle a given resource. That said, it is typically assumed that PUT is used for updating a given record. Obviously this is mostly semantic from ATHENA's standpoint. There may be potential wins on using third party libraries that make assumptions about the OPTIONS provided by a given resource.
On the topic of schemas: Gary clarified one important point for me: the fields resource is actually found at something like /tickets/fields. This makes a lot more sense for future development. Perhaps in the long run we should be thinking about the relationship as "a Ticket has a Schema" (which may imply multiple schemas). That way, client applications can consume what amounts to a flexible resource.
Finally, the props thing can be punted. The main reason I would see that flattened into the Ticket resource is to simplifying modeling the resource on the client side of things. It sounds like the cost outweighs the benefits in the short term.
Micah
----- Original Message -----
From: "Justin Karr" <justi...@fracturedatlas.org>
To: athena-t...@googlegroups.com
Sent: Wednesday, September 29, 2010 11:02:03 AM
Subject: RE: [athena-tix-devel] RESTful ATHENA
Micah,
I’m all for changing the architecture if it makes things better, but I don’t want to slow things down either.
POST-PUT:
We talked a lot about POST and PUT when we decided to break REST slightly by dropping PUT. I argued in favor of making it easier for client developers: one instruction to write, be it to add or to change. Am I crazy? Is ignoring PUT actually going to make things harder? How does this look from an application developer’s perspective? How important is this standard? I want ATHENA to be as standards-compliant as possible, and you’ll get the most support from me on changing this bit, provided we can make a decent argument for it and it doesn’t take a lot of time and resources to change.
SCHEMAS:
Under what scenario would we want multiple schemas for objects in a parakeet store like tickets? Does this help multi-tenancy (where multiple organizations are using the same ATHENA server)? Does this hurt or help searching across multiple companies’ tickets? Unless this is a big win for multi-tenancy (a big issue) and does not set back Fintan’s work on queries, I’m inclined to resist this.
PROPS as HASH:
Does having PROPS in a hash make things harder for client developers? Do we break standard practice by doing it this way? If not, this is the one I’m inclined to give the most push-back on as it is fairly intrinsic right now.
People outside the ATHENA core team: pipe up. I’d love your input on this.
Justin
From: athena-t...@googlegroups.com [mailto:athena-t...@googlegroups.com] On Behalf Of Micah Frost
Sent: Tuesday, September 28, 2010 8:08 PM
To: athena-t...@googlegroups.com
Subject: [athena-tix-devel] RESTful ATHENA
Hey all,
I've been reviewing the current resources provided by ATHENA-Tix, and want to bounce a few ideas off of the list.
Please refer to this wiki page: http://github.com/fracturedatlas/parakeet/wiki/Parakeet-Resources . Currently, the resources look something like this (if your mail reader has issues formatting this, I've posted it to github: http://gist.github.com/602034 ):
1. A uniform interface that falls in line with currently accepted usage for the 4 HTTP verbs. POSTing to a collective resource adds one to the collection.
2. Encapsulation of ATHENA logic surrounding the flexibility of the Ticket model. By flattening the Ticket into a single model without "props", the client is safe to assume the JSON returned describes the Ticket itself. A typical argument for returning a Ticket.props hash is to avoid naming collision with system names. Instead of letting such collisions dictate design, I would propose we use a prefixed underscore to indicate ATHENA-level properties. Then, users would not be allowed to submit field names that started with an underscore.
3. When the client does need to ask about what a Ticket looks like, the client can GET the schema. From a relationship standpoint, Ticket has one Schema; Schema has many fields. Fields have many values. Modeling the system in this manner allows the client to check on the schema and make assumptions during run time.