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:36:17 +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: <9237d2b2-b917-9a5a-f06e-923a13453537@w3.org>
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:36:47 UTC

This archive was generated by hypermail 2.3.1 : Monday, 16 May 2016 13:36:48 UTC