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

[Helge Heß]

On 26. May 2017, at 22:32, Paulo Faria via swift-server-dev <swift-server-dev at swift.org> wrote:
> I'm glad we can start talking in source code now.

Johannes’ stuff was source code too.

> Chris sent me the link before, so I had time to create a counterproposal concerning the 3 files mentioned. In the readme I have the rationale for the design decisions. I also used jazzy to create an API reference. Here are the links:

> No HTTP prefix

> There's no need to prefix the types with HTTP because 
> they are already defined inside the HTTP module

Swift modules are not really namespaces but just modules.
If you’d want a namespace, it should be sth like

  enum HTTP {
    class Request {}
  }

that would be kinda OK. In general I prefer just calling 
things what they are, HTTPRequest in this case.

The think you run into when using generic names is that:

  import HTTP
  import SOAP

let request = Request() // …

‘Request' is just too generic when looking at the source. It
makes some sense _within_ the implementing module, but
less in clients consuming the API.


> Nesting Method/Status

I guess that makes sense. I still find it weird to use
closed API (enums) for an open protocol. I’d prefer a
solution using constants.


> Lowercase Request.Method cases

That likely makes sense for consistency.


> Most common APIs are synchronous. Asynchronous APIs are 
> the exception in general

This is highly controversial :-) Both variants exist and
have their pros and cons, but that "Asynchronous APIs are 
the exception” sounds super weird. E.g. Node.js is
all asynchronous and the synchronous APIs are explicitly
marked via ‘sync’ (like readFileSync instead of the proper
readFile).

As I demonstrated before the API doesn't necessarily have to
be different. (my demo using Johannes' completely async API
on top of Apache, doing it completely synchronously).

In Swift async-vs-sync is clearly expressed by `@escaping`
in the signature. No specific naming needed in the first
place?


> Use UnsafeMutableRawBufferPointer and UnsafeRawBufferPointer 
> instead of Foundation.Data

In general, YES. But the proposal uses *DispatchData* and not
Data.
(Though I find it a little weird that Data is so specific now in the
 first place.)

As mentioned before, if you are performance aware, vectors
are kinda like a must. (which is what DispatchData can do
internally, though I think the API is AFAIK not exposed to
Swift)

hh