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