I am currently trying to implement the multiple
spaces proposal to see if
it is doable.
2015-07-03 11:52 GMT+02:00 vincent(a)massol.net <vincent(a)massol.net>et>:
On 3 Jul 2015 at 11:48:24, vincent(a)massol.net (vincent(a)massol.net(mailto:
vincent(a)massol.net)) wrote:
Just for the record, I’m -1 for the dotted
solution just for spaces as
I mentioned in the JIRA issue (
http://jira.xwiki.org/browse/XWIKI-12206?focusedCommentId=87137&page=co…
)
If we want to use “dots” then I much prefer that we use the serialized
reference
as in:
/rest/v2/type//ref/
Examples:
/rest/v2/property/wiki:space1.space2.page^object.property
/rest/v2/object/wiki:space1.space2.page^object
/rest/v2/attachment/wiki:space1.space2.page@filename
/rest/v2/page/wiki:space1.space2.page
/rest/v2/space/wiki:space1.space2
/rest/v2/wiki/wiki
I meant the following (to be self-describing):
/rest/v2/type/property/ref/wiki:space1.space2.page^object.property
/rest/v2/type/object/ref/wiki:space1.space2.page^object
/rest/v2/type/attachment/ref/wiki:space1.space2.page@filename
/rest/v2/type/page/ref/wiki:space1.space2.page
/rest/v2/type/space/ref/wiki:space1.space2
/rest/v2/type/wiki/ref/wiki
Thanks
-Vincent
Note that this leads to shorter and simpler
URLs.
Thanks
-Vincent
On 3 Jul 2015 at 11:20:14, Fabio Mancinelli (fabio.mancinelli(a)xwiki.com
(mailto:fabio.mancinelli@xwiki.com)) wrote:
> Hi,
>
> We should check how to declare a URI Template of the form
> /rest/wikis/xwiki/(spaces/SPACE)+/pages/PAGE in JAX-RS... The Spec
> allows regexs in the URI Template defintion in @Path annotations but
> this is something to be checked. I am not sure that it's that simple.
>
> Given the previous remark, maybe the dotted solution might be easier
to
handle.
>
> Of course API versioning is a very good thing to have.
>
> Thanks,
> Fabio
>
>
>
>
> On Fri, Jul 3, 2015 at 12:55 AM, Eduard Moraru wrote:
>> Hi,
>>
>> Initially, I wanted to go with the dots, however the backwards
>> compatibility problem would force us to either use a different key
than
>> "spaces" and deprecate
"spaces" or to introduce versioning (i.e.
path
>> prefix like /rest/v1/wikis...), as
Vincent said.
>>
>> However, the multiple "spaces" (I think this is what you meant,
Vincent)
>> alternative has more (I`d say only)
advantages than disadvantages.
So the
>> URL would be:
>>
>>
/xwiki/rest/wikis/xwiki/spaces/Europe/spaces/France/spaces/Paris/pages/WebHome
>>
>>
>> + is 100% backwards compatible
>> ++ old apps will only be able to access the first level, as they
were
>> designed
>> ++ No mixup between space name (unescaped) vs space reference
(escaped)
>> ++ As a result, no need to introduce any
versioningjust yet
>>
>> + indeed is much more restful, since at each step (e.g. France) you
can
>> have either subspaces (e.g. Paris) or
pages (e.g. WebHome or any
other
>> terminal page)
>> ++ in other words, the resource hierarchy is better exposed
>>
>> + Bonus, we stick to the good old "/" separator
>>
>> + Reflects perfectly the expansion of the model that we are doing
through
NS
>>
>> +1 for dots, i.e.
>> /xwiki/rest/wikis/xwiki/spaces/Europe.France.Paris/pages/WebHome
>>
>> - longer URLs for long paths
>>
>> So I`m +1 for the "multiple spaces" option.
>>
>> Thanks,
>> Eduard
>>
>> On Thu, Jul 2, 2015 at 6:14 PM, vincent(a)massol.net
>> wrote:
>>
>>> I think we should decide what we want independently of the REST
framework
>>> impl, to be the most restful
possible.
>>>
>>> Then we check how to do it in the REST fwk we currently use
(restlet)
and
>>> if not possible then we should check
if it’s possible with some
other REST
>>> fwk (jersey for example).
>>>
>>> At worse, if we don’t want to wait we will need at least to
introduce
API
>>> versioning so that we can change it
later on easily.
>>>
>>> There’s also the suggestion I proposed with several “pages”
elements
which
>>> seems potentially more restful than
dots to me (but leads to
longer urls).
>>>
>>> So IMO you should research more about what is the RESTful approach
to
this
>>> before we can decide anything.
>>>
>>> Thanks
>>> -Vincent
>>>
>>> On 2 Jul 2015 at 15:57:53, Guillaume Louis-Marie Delhumeau (
>>> gdelhumeau@xwiki.com(mailto:gdelhumeau@xwiki.com)) wrote:
>>>
>>>> Hi.
>>>>
>>>> This proposal is already explained in
>>>>
http://jira.xwiki.org/browse/XWIKI-12206. I think it is an
important
>>> issue
>>>> to fix because it blocks
http://jira.xwiki.org/browse/XWIKI-12198
>>> (Ensure
>>>> annotations work on nested spaces).
>>>>
>>>> The current REST URL for a space is:
>>>> /xwiki/rest/wikis/xwiki/spaces/Europe
>>>>
>>>> and for a page:
>>>> /xwiki/rest/wikis/xwiki/spaces/Europe/pages/WebHome
>>>>
>>>> The idea is to use dots as space separator in the REST URLs in
the
case
>>> of
>>>> nested spaces. Example:
>>>> /xwiki/rest/wikis/xwiki/spaces/Europe.France.Paris
>>>>
>>>> For spaces containing dots in their name, we simply escape them
with \
>>>> (%5C).
>>>>
>>>> It has the drawback to not have a similar URL than the standard
action,
>>> ie:
>>>> /xwiki/bin/view/Europe/France/Paris/WebHome - for view action
>>>> /xwiki/rest/wikis/xwiki/spaces/Europe.France.Paris/pages/WebHome
-
for
>>> REST
>>>> action
>>>>
>>>> But it does not seem possible to handle "/" in path parameters
with
>>> Restlet.
>>>> ie:
>>>> /xwiki/rest/wikis/xwiki/spaces/Europe/France/Paris/pages/WebHome
>>>> is not supported by Restlet.
>>>>
>>>> After a talk with some Restlet committers, they confirm me that
we
have
>>> to
>>>> write our own URL router to handle this. I don't know if it
worth the
>>> pain
>>>> although I don't have evaluated it.
>>>>
>>>> So I guess this proposal using dots is the best option, but I'm
free to
>>>> talk about this.
>>>>
>>>> Thanks,
>>>> Guillaume
>>>>
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Guillaume Delhumeau (gdelhumeau(a)xwiki.com)
Research & Development Engineer at XWiki SAS
Committer on the