W3C home > Mailing lists > Public > public-dwbp-wg@w3.org > May 2016

Re: API examples html

From: Phil Archer <phila@w3.org>
Date: Mon, 16 May 2016 14:48:55 +0100
To: Bernadette Farias Lóscio <bfl@cin.ufpe.br>, Annette Greiner <amgreiner@lbl.gov>, "public-dwbp-wg@w3.org" <public-dwbp-wg@w3.org>
Cc: Newton Calegari <newton@nic.br>
Message-ID: <bbd5c6a4-aae8-7dbf-8b7d-280904b868a2@w3.org>
Ignore that. I was looking at the wrong thing.

Sorry for spam

On 16/05/2016 14:36, Phil Archer wrote:
> Can I just ask why this example is presented in a separate document? It
> seems to me that it would fit within the primary document readily
> enough, no?
>
> Phil
>
> On 15/05/2016 15:24, Bernadette Farias Lóscio wrote:
>> Hi Annette,
>>
>> Thanks again for your feedback!
>>
>> I made some more changes on the API documentation and I think now it's ok
>> [1]!
>>
>> Cheers,
>> Berna
>>
>> [1] http://w3c.github.io/dwbp/dwbp-api-example.html
>>
>>
>>
>> 2016-05-13 17:59 GMT-03:00 Annette Greiner <amgreiner@lbl.gov>:
>>
>>> Seeing URIs in there, and separate IDs, I thought your were trying to
>>> do a
>>> hypermedia API thing and offer links, but I guess now you are just
>>> suggesting them as ids. If you just want to use URIs as identifiers,
>>> we say
>>> in BP11 to define locally unique identifiers and allow them to be
>>> converted
>>> to the globally unique, long URIs. But I'm not sure bus stops are a good
>>> example of BP11. They can be pretty changeable. In any case, I wouldn't
>>> write an API call that returns primarily non-URL URIs. If we fleshed out
>>> the routes result so that it's more complete, like the stops result, it
>>> would help. The real-time result uses /id in URIs labeled as "route". I
>>> think the route number alone would be correct there.
>>>
>>> I think the URIs for 24 and 26 are okay.
>>>
>>> http://w3c.github.io/dwbp/bp.html#APIHttpVerbs doesn't seem to be
>>> pointing where you want it to point.
>>> -Annette
>>>
>>>
>>> On 5/13/16 7:46 AM, Bernadette Farias Lóscio wrote:
>>>
>>> Hi Annette,
>>>
>>> thanks a lot for the fast response! We're gonna fix the html page
>>> based on
>>> your comments.
>>>
>>> I have just one comment about: "4. In the responses, any URIs should be
>>> real URLs. They should never have “/id” in them. I think the route
>>> values
>>> should just be a route id number, {“route”: 5}. Giving a URI for a thing
>>> here is not friendly to developers."
>>>
>>> We included the /id because of the example given at BP11 [1]. In this
>>> case, can we keep the /id?
>>>
>>> I think it's possible to improve the API documentation for the next
>>> publication. I'm gonna discuss this with Newton and we're gonna let you
>>> know about our progress.
>>>
>>> I sent you another message asking your feedback on the URIs used in BP
>>> 24[1] and BP 26[2]. We rewrote the URIs to follow the same pattern
>>> used in
>>> the API documentation, but we are not sure if this is correct. If you
>>> prefer we can use the original ones.
>>>
>>> Cheers,
>>> Berna
>>>
>>> [1] http://w3c.github.io/dwbp/bp.html#identifiersWithinDatasets
>>>
>>> [1] http://w3c.github.io/dwbp/bp.html#APIHttpVerbs
>>> [2]http://w3c.github.io/dwbp/bp.html#avoidBreakingChangesAPI
>>> 11:31 (Há 15 minutos)
>>>
>>>
>>> 2016-05-13 11:31 GMT-03:00 Annette Greiner <amgreiner@lbl.gov>:
>>>
>>>> Hi Bernadette,
>>>> The example documentation is looking nice! I like the format, though it
>>>> could give more detail.
>>>>
>>>> I really wish this used Swagger, because that’s such a great example.
>>>> Take a look at http://petstore.swagger.io/#!/pet/addPet and click on
>>>> one
>>>> of the calls to expand it. You’ll see what I’m talking about. They
>>>> have a
>>>> nice table that lists parameters and lets you test options right in
>>>> the web
>>>> page. If we can’t use Swagger itself, could we emulate it more
>>>> closely? I
>>>> think some in-page javascript is all we would need. That would
>>>> probably be
>>>> too much to set up for this version of the BP doc, but I think we
>>>> could add
>>>> it for the next one.
>>>>
>>>> I noticed some small errors, detailed below.
>>>>
>>>> 1. The first call, “List all bus routes" has a space for an example,
>>>> but
>>>> there isn’t an example in there. I think you could just remove the
>>>> heading.
>>>>
>>>> 2. In the call to list all bus stops, the example doesn’t match. I
>>>> think
>>>> you have the beginnings of one call with the example and results from
>>>> another. You don’t need an example for the listing of all bus stops,
>>>> but
>>>> you should show the response.
>>>>
>>>> The call for all the stops on a specific bus route should be like this:
>>>>
>>>> List all bus stops along a single route
>>>> GET http://data.mycity.example.com/transport/api/bus/stops/route/{id}
>>>> Example
>>>> http://data.mycity.example.com/transport/api/bus/stops/route/5
>>>>
>>>> The result should return the same fields for each stop. Right now it
>>>> returns three completely different objects.
>>>>
>>>> 3. The example for "Get real-time info for bus stop” doesn’t match the
>>>> call. It should be
>>>> http://data.mycity.example.com/transport/api/bus/stops/realtime/345
>>>>
>>>> 4. In the responses, any URIs should be real URLs. They should never
>>>> have
>>>> “/id” in them. I think the route values should just be a route id
>>>> number,
>>>> {“route”: 5}. Giving a URI for a thing here is not friendly to
>>>> developers.
>>>>
>>>> -Annette
>>>>
>>>>
>>>>
>>>
>>>
>>> --
>>> Bernadette Farias Lóscio
>>> Centro de Informática
>>> Universidade Federal de Pernambuco - UFPE, Brazil
>>>
>>> ----------------------------------------------------------------------------
>>>
>>>
>>>
>>> --
>>> Annette Greiner
>>> NERSC Data and Analytics Services
>>> Lawrence Berkeley National Laboratory
>>>
>>>
>>>
>>
>>
>

-- 


Phil Archer
W3C Data Activity Lead
http://www.w3.org/2013/data/

http://philarcher.org
+44 (0)7887 767755
@philarcher1
Received on Monday, 16 May 2016 13:49:25 UTC

This archive was generated by hypermail 2.3.1 : Monday, 16 May 2016 13:49:25 UTC