[Mailman-Developers] Architecture for extra profile info

[Xu Wang]

On Sat, Apr 27, 2013 at 6:34 AM, Richard Wackerbarth <rkw at dataplex.net>wrote:

>
> On Apr 27, 2013, at 8:19 AM, "Stephen J. Turnbull" <stephen at xemacs.org>
> wrote:
>
> > Richard Wackerbarth writes:
> >
> >>> "ABCDEFG" is what?  The list?
> >>
> >> Yes. But note that it is some pk provided by the list store.
> >
> > "pk" ?
>
> Primary Key == An identifier of the server's choice that identifies a
> unique instance of the specified resource.
> It is important to note that the client CANNOT rely on any particular
> scheme for mapping other keys to this identifier.
>
> >>>>
> https://server.example.com/mailman/attribute/posting_address/test_list@example.comwould return the URI representing the list
> >>>
> >>> Why have you changed the order of components here?
> >>
> >> Because I don't know the pk for the list. I wish to look it up.
> >
> > So "attribute/posting_address/test_list at example.com" is a query that
> > means "give me a way to indicate this list"?
>
> Yes
>
> > These URIs are pretty ugly.  Surely we can do better?
>
> Perhaps we can. But we need to conform to the HAL framework style.
>
> As I understand it, the consumer understands the semantics of various
> links, but the actual links are "discovered" as a part of previous queries
> and not "constructed".  As such, the links depend more on the ease of
> implementation rather than their "beauty".
>
> Perhaps Xu has experience and can enlighten us.
>
>
The rules of good endpoint is very simple.
             * For first-class resources
                   collections endpoint:
<domain>/<api_prefix>/<version>/<collection name>/
                         e.g. http://list.mailman.org/api/v1/users
                   document endpoint:
<domain>/<api_prefix>/<version>/<collection name>/<doc_id>/
                         e.g.
http://list.mailman.org/api/v1/users/ID1234567/
             * Don't use path as tools of deep query, use query string for
query
                         e.g.
http://list.mailman.org/api/v1/users/?subscriptions="mailing_list_abc"
             * Use hyperlinks for references between first-class resources
in documents:
                         e.g. curl
localhost:5000/api/v1/users/?max_results=2 | python -mjson.tool
{
    "_items": [
        {
            "_id": "517b88e4f84a4b15f756a1af",
            "_links": {
                "self": {
                    "href":
"localhost:5000/api/v1/users/517b88e4f84a4b15f756a1af/",
                    "title": "user"
                }
            }, ...
        },
        {
            "_id": "517b88e4f84a4b15f756a1b0",
            "_links": {
                "self": {
                    "href":
"localhost:5000/api/v1/users/517b88e4f84a4b15f756a1b0/",
                    "title": "user"
                }
            },
...
    ],
    "_links": {
        "next": {
            "href": "localhost:5000/api/v1/users/?max_results=2&page=2",
            "title": "next page"
        },
        "parent": {
            "href": "localhost:5000/api/v1",
            "title": "home"
        },
        "self": {
            "href": "localhost:5000/api/v1/users/",
            "title": "users"
        }
    }
}