URL Design Choices

["Paul B. Anderson" <pa...@pnlassociates.com>]

I'm beginning to build an Atom server based on Abdera and I am unclear 
on what I should do for the URLs.  It seems to be an important aspect of 
designing creating the server but the tutorials do not go into the 
requirements and ramifications.

I have read the Atom RFCs.  I don't have a problem with the service 
document or an individual entry.  The Server Implementation Guide 
(excerpt shown below) shows in line 34, for example, a number of 
possibilities following collection that I did not see explained.

Can provide any general guidance for setting up URLs or point me to 
something that provides some additional information?  I am particularly 
interested in:

1.  What is required to be RFC-compliant or to conform to current practice.
2.  What URLs Abdera will handle automatically and what I must implement.
3.  Clarification distinguishing the functions of TargetResolver and 
TargetBuilder.

Thanks!

Paul


22   setTargetResolver(
23       new RegexTargetResolver()
24         .setPattern("/atom(\\?[^#]*)?", TargetType.TYPE_SERVICE)
25         .setPattern("/atom/([^/#?]+);categories", 
TargetType.TYPE_CATEGORIES, "collection")
26         .setPattern("/atom/([^/#?;]+)(\\?[^#]*)?", 
TargetType.TYPE_COLLECTION, "collection")
27         .setPattern("/atom/([^/#?]+)/([^/#?]+)(\\?[^#]*)?", 
TargetType.TYPE_ENTRY, "collection","entry")
28         .setPattern("/search", 
OpenSearchFilter.TYPE_OPENSEARCH_DESCRIPTION)
29     );
30
31     setTargetBuilder(
32       new TemplateTargetBuilder()
33         .setTemplate(TargetType.TYPE_SERVICE, "{target_base}/atom")
34         .setTemplate(TargetType.TYPE_COLLECTION, 
"{target_base}/atom/{collection}{-opt|?|q,c,s,p,l,i,o}{-join|&|q,c,s,p,l,i,o}")
35         .setTemplate(TargetType.TYPE_CATEGORIES, 
"{target_base}/atom/{collection};categories")
36         .setTemplate(TargetType.TYPE_ENTRY, 
"{target_base}/atom/{collection}/{entry}")
37 .setTemplate(OpenSearchFilter.TYPE_OPENSEARCH_DESCRIPTION, 
"{target_base}/search")
38     );

RE: URL Design Choices

["Rushforth, Peter" <Pe...@NRCan-RNCan.gc.ca>]

Hi Paul,

Don't know if you'll get a reply from others, so thought I would chip in with a couple of thoughts. 

>1.  What is required to be RFC-compliant or to conform to current practice.
I don't think there are any constraints put on what your URLs look like by the RFCs.  AFAIK anyway.
Simplicity and consistency would be important, of course.  I think best practices might say that URLs
should be discovered in your representations, if they're important to your api.  Use appropriate link relations
to make them understandable.

>2. What URLs Abdera will handle automatically and what I must implement.

I don't think Abdera will handle any URLs automatically, you must build your servlet and deploy it yourself.  Abdera 
may provide some plumbing code to help.  You may be able to draw on the example code as a basis for
what the Abdera devs were thinking when they designed the framework.  

Related to that, and my suggestion for your third question:

> 3.  Clarification distinguishing the functions of TargetResolver and TargetBuilder.

I have not used TargetBuilder myself.  A TargetResolver identifies the nature of the request based on URL and headers, so that it can be mapped
to the appropriate handling code.  I imagine that TargetBuilder would be useful for generating links in a consistent manner.

The example code is what you should go by in the absence of more detailed docs (and/or advice from others on
this list!).

HTH.

Good luck.
Peter Rushforth

-----Original Message-----
From: Paul B. Anderson [mailto:paul.a@pnlassociates.com] 
Sent: February 3, 2015 11:39
To: user@abdera.apache.org
Subject: URL Design Choices

I'm beginning to build an Atom server based on Abdera and I am unclear on what I should do for the URLs.  It seems to be an important aspect of designing creating the server but the tutorials do not go into the requirements and ramifications.

I have read the Atom RFCs.  I don't have a problem with the service document or an individual entry.  The Server Implementation Guide (excerpt shown below) shows in line 34, for example, a number of possibilities following collection that I did not see explained.

Can provide any general guidance for setting up URLs or point me to something that provides some additional information?  I am particularly interested in:

1.  What is required to be RFC-compliant or to conform to current practice.
2.  What URLs Abdera will handle automatically and what I must implement.
3.  Clarification distinguishing the functions of TargetResolver and TargetBuilder.

Thanks!

Paul


22   setTargetResolver(
23       new RegexTargetResolver()
24         .setPattern("/atom(\\?[^#]*)?", TargetType.TYPE_SERVICE)
25         .setPattern("/atom/([^/#?]+);categories", 
TargetType.TYPE_CATEGORIES, "collection")
26         .setPattern("/atom/([^/#?;]+)(\\?[^#]*)?", 
TargetType.TYPE_COLLECTION, "collection")
27         .setPattern("/atom/([^/#?]+)/([^/#?]+)(\\?[^#]*)?", 
TargetType.TYPE_ENTRY, "collection","entry")
28         .setPattern("/search", 
OpenSearchFilter.TYPE_OPENSEARCH_DESCRIPTION)
29     );
30
31     setTargetBuilder(
32       new TemplateTargetBuilder()
33         .setTemplate(TargetType.TYPE_SERVICE, "{target_base}/atom")
34         .setTemplate(TargetType.TYPE_COLLECTION, 
"{target_base}/atom/{collection}{-opt|?|q,c,s,p,l,i,o}{-join|&|q,c,s,p,l,i,o}")
35         .setTemplate(TargetType.TYPE_CATEGORIES, 
"{target_base}/atom/{collection};categories")
36         .setTemplate(TargetType.TYPE_ENTRY, 
"{target_base}/atom/{collection}/{entry}")
37 .setTemplate(OpenSearchFilter.TYPE_OPENSEARCH_DESCRIPTION,
"{target_base}/search")
38     );