[swift-server-dev] Prototype of the discussed HTTP API Spec

[Chris Bailey]

> 1)
> One thing I would like to see is a separate item in the repository that 
contains just the actual API. Instead of the API intermingled with the > 
concrete implementation. Similar to what Johannes’ did. Could be a 
document called API.md.
> Update this when the API changes due to workgroup work.

Which would be more preferable, a full Jazzy-built API doc, just a .md 
file or both? I'd prefer not to take the multi-branch approach if 
possible, if nothing else because of the difficulty in keeping the 
branches in sync. We should be able to propose implementation changes via 
PRs that people can clone, test and compare, and we can merge in what 
makes sense - removing blue-socket is a good example.


> 2)
> The other thing that would be nice is a demo tool in the Sources 
directory, again similar to what Johannes showed (his tiny echod sample).

It looks like Carl has done that already in SimpleResponseCreator.swift:
        
https://github.com/carlbrown/HTTPSketch/blob/master/Sources/HTTPSketch/SimpleResponseCreator.swift
Giving it a more obvious name makes sense - along with documenting it in 
the README.md, etc.

Chris




From:   Helge Heß via swift-server-dev <swift-server-dev at swift.org>
To:     swift-server-dev <swift-server-dev at swift.org>
Date:   30/05/2017 11:54
Subject:        Re: [swift-server-dev] Prototype of the discussed HTTP API 
Spec
Sent by:        swift-server-dev-bounces at swift.org



Hi,

+1 on Chris’ comment.

Two wishes:

1)
One thing I would like to see is a separate item in the repository that 
contains just the actual API. Instead of the API intermingled with the 
concrete implementation. Similar to what Johannes’ did. Could be a 
document called API.md.
Update this when the API changes due to workgroup work.

Or more fancy: Put just the API (and no2 below) into the master branch. 
The same .swift files, just w/o any implementation code. (Yes, this won’t 
compile of course). Then have branches for concrete implementations, say 
‘blue-socket’ for the current one.
This way the API can evolve in master and you can always see where the 
concrete implementation is at, and other people can contribute different 
implementations for comparison (e.g. the low hanging fruit would be a 
simple one that doesn’t require a socket library but just libdispatch).

2)
The other thing that would be nice is a demo tool in the Sources 
directory, again similar to what Johannes showed (his tiny echod sample).

hh

> On 30. May 2017, at 12:08, Chris Bailey via swift-server-dev 
<swift-server-dev at swift.org> wrote:
> 
> Hi Paulo: 
> 
> One of the things we're trying to avoid is a waterfall design approach, 
requiring a fully settled API before any implementation work starts - its 
much more preferable to have a reasonable starting point, make it work, 
and then make it better. One of the advantages of this approach is that it 
widens the funnel of participation out from "API designers" to include 
users, who can try out the API and provide feedback. 
> 
> The proposal that's been implemented was the result of a number of weeks 
of debate on the mailing list, and as such gives us that starting point. 
That doesn't mean that your proposal is ignored - in fact it gives us an 
excellent list of areas that we can debate incrementally and see what the 
effect would be via working use cases and performance tests. 
> 
> That then gets us working and collaboration on on a single code base - 
which is really the primary goal of the workgroup! 
> 
> Chris 
> 

_______________________________________________
swift-server-dev mailing list
swift-server-dev at swift.org
https://lists.swift.org/mailman/listinfo/swift-server-dev



Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number 
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6 3AU

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-server-dev/attachments/20170530/ede4e9d9/attachment.html>