Re: API examples html

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
>
>
>


-- 
Bernadette Farias Lóscio
Centro de Informática
Universidade Federal de Pernambuco - UFPE, Brazil
----------------------------------------------------------------------------