We discussed this issue a bit in the IRC channel today. Some points that
were raised:
- The API that we release for 1.0 should be stable through 2.0.
- *but* we haven't pushed the REST API very hard yet or put a lot of
thought into designing it, so constraining ourselves to a stable
API might
be a big mistake.
- Having two REST endpoints for getting (possibly filtered) lists of maps
(one at /maps/ or /maps/api/ or whatever for getting the collection of maps,
and one at /maps/search/ for searching maps) is a little weird.
- Suffixing all our API URLs with /api/ is not pretty. It would be more
RESTful to use an Accept: HTTP header or a .json suffix to specify the
format.
- Following the URL design principle of general -> specific, a possible
structure for our API could be:
- /search/ -> search through all records
- /search/maps/ -> search through maps only
- /search/layers/ -> search through layers only
Personally, I think it is a bit late in the game to be considering adding
"stable REST API" to the featureset for GeoNode 1.0. Our REST API is just
plumbing so we can do some AJAX stuff for the web UI. (If it helps, I'm
glad to start calling it something other than "API" to get across the fact
that it's a detail of the system implementation.)
In particular, I don't think relying on HTTP headers is a great way to go
because Django does routing based on only the path.
So, here how I read Seb's latest proposal:
- /data/ : the data search page, minus the results list and plus some
friendly text. this is an HTML resource only, not intended for automated use
- /data/search: The data search results page, with AJAXy search features
- /data/search/api: Proxy for CSW requests, rewrites the XML to
Ext-friendly JSON
- /community: A map search page, minus the results list and plus some
friendly text. Being removed cause the URL's a bit weird.
- /maps: A listing of all maps on the site in JSON format. Being *
removed* because we want the map search page here, plus an unfiltered
list of maps isn't that useful.
- /maps: In place of the map listing, we'll *add* *a map search page,
minus the results list and plus some friendly text*
- /maps/search: A map search results page, with AJAXy search features
- /maps/search/api: Server-side component of the map search AJAX updates
I don't think this is the ideal URL structure. However, I think getting the
URLs for pages right is more important than the URLs for APIs (I'd estimate
that GeoNode bookmarks will quickly outpace the 3rd-party REST client
development.) Let's focus on the (public) REST API for a future release.
With that in mind, I'm +1 on binding /maps/ to the map welcome page or
whatever you want to call it. I suppose with the recent revamp of the map
search, we are done with the JSON map listing entirely?
-d
On Thu, Aug 26, 2010 at 11:19 AM, Sebastian Benthall <[email protected]>wrote:
> Sorry, I thought it was clear from context that axing the maps/api endpoint
> meant going with the Alternative proposal in the previous email.
>
> On Thu, Aug 26, 2010 at 11:11 AM, David Winslow <[email protected]>wrote:
>
>> If you are changing your proposal I'd like to see the new version.
>>
>> -d
>>
>> On Thu, Aug 26, 2010 at 11:10 AM, Sebastian Benthall <[email protected]>wrote:
>>
>>> Also, does this mean you have no remaining objections?
>>>
>>> On Thu, Aug 26, 2010 at 10:45 AM, David Winslow <[email protected]>wrote:
>>>
>>>> See also:
>>>> http://stackoverflow.com/questions/389169/best-practices-for-api-versioning
>>>>
>>>>
>>>> On Thu, Aug 26, 2010 at 10:40 AM, Sebastian Benthall
>>>> <[email protected]>wrote:
>>>>
>>>>> I'm +1 axing the full json dump for maps
>>>>>
>>>>>
>>>>> On Thu, Aug 26, 2010 at 10:37 AM, David Winslow
>>>>> <[email protected]>wrote:
>>>>>
>>>>>> Is this a useful distinction? It seems like having a filterable
>>>>>> listing is better than having a listing and a search, api-wise. In
>>>>>> fact, we
>>>>>> should probably enforce a maximum page size on the listing query either
>>>>>> way.
>>>>>>
>>>>>> -d
>>>>>>
>>>>>> On Thu, Aug 26, 2010 at 10:31 AM, Sebastian Benthall <[email protected]
>>>>>> > wrote:
>>>>>>
>>>>>>> The difference between /maps and /maps/search/api currently is that
>>>>>>> /maps is a straight json dump of all the map configurations, and
>>>>>>> /maps/search/api provides extra information about the search in its
>>>>>>> results
>>>>>>> and accepts query parameters that are useful especially if you are
>>>>>>> trying to
>>>>>>> populate a paging Extjs table with the results.
>>>>>>>
>>>>>>>
>>>>>>> On Thu, Aug 26, 2010 at 10:27 AM, David Winslow <
>>>>>>> [email protected]> wrote:
>>>>>>>
>>>>>>>> What is the distinction between an API and a Search API?
>>>>>>>>
>>>>>>>> -d
>>>>>>>>
>>>>>>>>
>>>>>>>> On Thu, Aug 26, 2010 at 10:22 AM, Sebastian Benthall <
>>>>>>>> [email protected]> wrote:
>>>>>>>>
>>>>>>>>> *Proposal for 1.0:*
>>>>>>>>>
>>>>>>>>> /data
>>>>>>>>> /data/search
>>>>>>>>> /data/search/api
>>>>>>>>>
>>>>>>>>> /maps *<-- the only proposed change*(s)
>>>>>>>>> /maps/api *<-- the only proposed change*(s)
>>>>>>>>> /maps/search
>>>>>>>>> /maps/search/api
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> *Alternative proposal for 1.0:*
>>>>>>>>> Same as a above but dropping maps/api entirely.
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> *Speculative proposal for future release:*
>>>>>>>>>
>>>>>>>>> /search
>>>>>>>>> /search/api
>>>>>>>>>
>>>>>>>>> /data
>>>>>>>>> /data/api --> ???
>>>>>>>>> /data/search --> redirects to /search?flag=data
>>>>>>>>> /data/search/api --> redirects to /search/api?flag=data
>>>>>>>>>
>>>>>>>>> /maps
>>>>>>>>> /maps/api --> full json dump
>>>>>>>>> /maps/search --> redirects to /search?flag=maps
>>>>>>>>> /maps/search/api --> redirects to /search/api?flag=maps
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Thu, Aug 26, 2010 at 10:04 AM, David Winslow <
>>>>>>>>> [email protected]> wrote:
>>>>>>>>>
>>>>>>>>>> It would be nice to flesh this out a bit to avoid shifting URLs
>>>>>>>>>> around after the 1.0 release if we can help it.
>>>>>>>>>>
>>>>>>>>>> -d
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> On Thu, Aug 26, 2010 at 9:53 AM, Sebastian Benthall <
>>>>>>>>>> [email protected]> wrote:
>>>>>>>>>>
>>>>>>>>>>> Currently combined maps and data search is unspecified except for
>>>>>>>>>>> "it would be nice to combine maps and data search some day."
>>>>>>>>>>>
>>>>>>>>>>> So I suppose this doesn't interact with those plans at all.
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> On Thu, Aug 26, 2010 at 8:59 AM, David Winslow <
>>>>>>>>>>> [email protected]> wrote:
>>>>>>>>>>>
>>>>>>>>>>>> How does this interact with plans to unify map search with data
>>>>>>>>>>>> search?
>>>>>>>>>>>>
>>>>>>>>>>>> -d
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>> On Wed, Aug 25, 2010 at 9:49 PM, Ariel Nunez <
>>>>>>>>>>>> [email protected]> wrote:
>>>>>>>>>>>>
>>>>>>>>>>>>> > I propose we change the url structure in these ways:
>>>>>>>>>>>>> > /maps - overview page of GeoNode's map-related tools
>>>>>>>>>>>>> (was /community )
>>>>>>>>>>>>> > /maps/api - a json dump of all map configurations
>>>>>>>>>>>>>
>>>>>>>>>>>>> +1
>>>>>>>>>>>>>
>>>>>>>>>>>>> I thought about this issue too a couple of weeks ago, and agree
>>>>>>>>>>>>> with
>>>>>>>>>>>>> your proposal.
>>>>>>>>>>>>>
>>>>>>>>>>>>> Ariel
>>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>> --
>>>>>>>>>>> Sebastian Benthall
>>>>>>>>>>> OpenGeo - http://opengeo.org
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> --
>>>>>>>>> Sebastian Benthall
>>>>>>>>> OpenGeo - http://opengeo.org
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Sebastian Benthall
>>>>>>> OpenGeo - http://opengeo.org
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Sebastian Benthall
>>>>> OpenGeo - http://opengeo.org
>>>>>
>>>>>
>>>>
>>>
>>>
>>> --
>>> Sebastian Benthall
>>> OpenGeo - http://opengeo.org
>>>
>>>
>>
>
>
> --
> Sebastian Benthall
> OpenGeo - http://opengeo.org
>
>
