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

Re: API BPs Example

From: Phil Archer <phila@w3.org>
Date: Tue, 3 May 2016 23:09:29 +0100
To: Annette Greiner <amgreiner@lbl.gov>, public-dwbp-wg@w3.org
Message-ID: <983d6e44-2b6c-5511-17b2-a3709d206899@w3.org>
Just an aside... you can have whatever static files you like alongside 
the publication, so if you want to include some static JSON files, 
that's fine. If you want to include some functioning JavaScript, that is 
probably OK too (but I'd have to check). What we can't do is set up an 
actual service/API that needs maintenance.

On the example.com issue, if needed, we can say that, for the purpose of 
documentation we use example.com but where these link to actual 
resources these are hosted on w3.org (or something like that).

Phil

On 03/05/2016 19:43, Annette Greiner wrote:
> A few more notes on looking some more at the documentation. You
> shouldn't need to include URL parameters, since the URL itself should
> determine what gets returned.
>
> For example,
> /bus/stops     returns the full list
> /bus/stops/route/11     returns the list of stops for route 11 only
>
> 'transport-agency' is just part of the base URL for the API, so that
> wouldn't be a parameter.
> 'full details' or not for an API like this seems unnecessary, because
> the difference in size would be so small that it wouldn't matter.
> -Annette
>
> On 5/3/16 8:35 AM, Deirdre Lee wrote:
>> |Hi,
>>
>> I've created an example that can be used for the API BPs|
>>
>>     |Best Practice 21: Provide real-time access |
>>     |Best Practice 23: Make data available through an API|
>>     |Best Practice 24: Use Web Standards as the foundation of APIs|
>>     |Best Practice 25: Provide complete documentation for your API|
>>
>> |
>> https://www.w3.org/2013/dwbp/wiki/Api_example
>> |
>>
>>     |GET /bus/routes|
>>     |GET /bus/stops|
>>     |GET /bus/realtime|
>>     ||
>>
>> |
>> For 'GET /bus/stops', I've used three different ways to describe
>> bus-stops:
>> |
>>
>>   * |using simple fields, |
>>   * |using fields defined in
>>     http://w3c.github.io/dwbp/dwbp-example.html and |
>>   * |using geojson to describe lat/long.|
>>
>> |We should pick one approach. I think the third - simple fields and
>> geojson.
>> |
>>
>> |What do you think?
>> |
>>
>> |Cheers,
>> Deirdre
>> |
>>
>> --
>> ------------------------------------
>> Deirdre Lee, CEO & Founder
>> Derilinx - Linked & Open Data Solutions
>>   Web:www.derilinx.com
>> Email:deirdre@derilinx.com
>> Address:  11/12 Baggot Court, Dublin 2, D02 F891
>> Tel:      +353 (0)1 254 4316
>> Mob:      +353 (0)87 417 2318
>> Linkedin: ie.linkedin.com/in/leedeirdre/
>> Twitter:  @deirdrelee
>

-- 


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

http://philarcher.org
+44 (0)7887 767755
@philarcher1
Received on Tuesday, 3 May 2016 22:09:43 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 3 May 2016 22:09:43 UTC