search

srnsw / api.records.nsw.gov.au

State Records NSW API
http://api.records.nsw.gov.au
GNU Affero General Public License v3.0
3 stars 0 forks source link

Rails and Accept headers #28

Closed richardlehane closed 13 years ago

richardlehane commented 13 years ago

The API currently relies on format prefixes (.xml) or parameters (format=xml) to specify the return format. Would perhaps be more RESTFUL to support HTTP headers as well (e.g. HTTP Accept: application/xml).

At present API doesn't support this, or only inconsistently. Can check this out at http://hurl.it/ (a great site for exploring APIs).

e.g. when ask for application/xml from search it breaks: http://hurl.it/hurls/cdf5617e12dfba07fa036e9d35bbb083d5c0a857/83b3468479bfca5e15443f7a9b6d58c70b735517

As do most other entities: http://hurl.it/hurls/e365cf5d5bee98678524f408be5f05b969c19d36/8f9972755adc2c10bbc73d5e3df7c61eab262b79

Series does work with accept headers - but weirdly, you get rdf-zotero (probably because I set application/xml as a mime type for this):

http://hurl.it/hurls/1f86288f5332d8f25f310fd68b9e294f06b0141c/5f383e270b900fa994b0bc3325161ba675c303d6

So we should look at the mime types we assign to views (e.g. rdf-zotero might be better expressed as a custom mime type) and we should make sure that generic xml and json can be returned using accept header.

wisanup commented 13 years ago

I am digging this down and found that Rails will render result as following scenarios

accept => application/xml, Rails will always render rdf-zotero on any page accept => text/xml, Rails will always render XML on any page accept => application/json, Rails will always render JSON on any page

In this case, just change the accept header to 'text/xml' would get rid of the errors. Are you OK with that?

richardlehane commented 13 years ago

Prefer not using text/xml (for reason that follows). How about "application/mods+xml", "application/eac_cpf+xml", "application/oai_dc+xml" and "application/rdf_zotero+xml"?

http://restpatterns.org/Glossary/MIME_Type XML MIME Types

The most common XML MIME types are application/xml and text/xml. Note that the latter is discouraged, because it uses the Latin1 character set by default. However, for XML MIME types, there is also a provision to allow for an infinite number of recognizable XML MIME types by using the +xml suffix (e.g. application/atom+xml, application/xhtml+xml, ...).

In general, XML MIME types are of the form application/*+xml with the notable exception of SVG, which is image/svg+xml.

richardlehane commented 13 years ago

did a little more reading: "application/mods+xml" is actually registered with IANA and correct to use (http://www.rfc-editor.org/rfc/rfc6207.txt). the others are made up and we might want indicate this with "x." prefixes??: so "application/mods+xml"; and "application/x.eac_cpf+xml", "application/x.oai_dc+xml", "application/x.rdf_zotero+xml"

wisanup commented 13 years ago

Fixed at https://github.com/srnsw/api.records.nsw.gov.au/commit/67ba192a58f6cdb86940d1650333f0c7407f3990