search

apis-json / api-json

APIS.json an API discovery format
http://apisjson.org/
MIT License
111 stars 23 forks source link

well known url / content-type negotiation #12

Open OriPekelman opened 10 years ago

OriPekelman commented 10 years ago

I think it is harmful to have well known urls with different file type terminations (".txt, .json...").

This means bots will have to guess... and try each and every posssibility....

Better would be to use contet-type negotiation, and mandate that the default is JSON for example. So I would go for simply /apis.

But then again, it might also be better not to compete for a "reserved uri" like this and go for something like rfc5785 https://www.mnot.net/blog/2010/04/07/well-known so... /.well-known/apis

njyx commented 10 years ago

The consensus has been actually just to have .json (and not support different formats for now).

OriPekelman commented 10 years ago

Should I therfor not refer to apisjson_0.13.txt as the current draft? is there a more recent one?

njyx commented 10 years ago

Comments on 0.13 are great. We're currently working on 0.14, to address a bunch of them - should be pushed this weekend.

OriPekelman commented 10 years ago

note, testing https://www.google.com/search?as_q=apis&as_occt=url seems to indicate there are some very important domains in which /apis is taken (linked-in, google)

njyx commented 10 years ago

Hi Ori, thanks again for the inputs - processing. Good to meet you.

I'm not sure why this is a problem - we're planning to use apis.json & hence with the file termination. I t might be a problem if we go into multi formats and allow /apis as an overload. However we can check.

OriPekelman commented 10 years ago

I am really not sure using the url "apis" on the root with json termination is a good idea.

  1. Either this thing works, and we will have to live with it for a very long time (wouldn't you have liked to have robots.txt, sitemap.xml a bit more extensible and future proof right now?). This then might pollute our global namespace for a decade or two. Well known URLs are impossible to version. You can not change your mind later. Because this is something that is hardcoded in all clients;
  2. Or it doesn't and then who cares.

For me the design decisions must take two elements into account: Usability and simplicity to try to deal with (2) and get people to use it. But also ecology (do not pollute a global namespace, know what can be versioned what can not be, use and promote exisiting standards).

njyx commented 10 years ago

Having something in the root (or having something elsewhere) and as a well known is actually precisely the point. The problem is there is no "bootstrap" mechanism at all for search right now. I have no way to go to a domain and find where the APIs are. So it's really like sitemap.xml.

The reverse problem (rel back from the API itself) which you mention in another thread is also important and we'll add it (we plan just to use "described-by" which exists) - but it's the less important one at the moment.

You only have two paths: make everybody register in registries - this explodes with the number of registries, or have a location on the server you can use.