[Proposal] EndPoint: Specify full path with placeholders

[Tarmil]

Proposal: make the EndPoint syntax more complete by specifying the full path with {field} placeholders.

Example:

type Page =
    | [<EndPoint "/article/{id}/{slug}">] Article of id: int * slug: string
    | [<EndPoint "/foo/{b}/bar/{a}">]     MoreComplex of a: (int * string) * b: int

Article(123, "some-string") // -> /article/123/some-string
MoreComplex(456, (123, "some-string")) // -> /foo/123/some-string/bar/456

• If an EndPoint is just one non-placeholder fragment, it works like currently: fields are added one after another.

• It is an error for an EndPoint to specify some but not all of the fields.

• This should support multiple endpoints with a common prefix. For example:

  type CommonConstantPrefix =
      | [<EndPoint "/article/by-id/{id}">]     ById of id: int
      | [<EndPoint "/article/by-slug/{slug}">] BySlug of slug: string
      | [<EndPoint "/article/{slug}">]         Article of slug: string

  In the above:

  • any path starting with /article/by-id is matched with ById
  • any path starting with /article/by-slug is matched with BySlug
  • any other path starting with /article is matched with Article.

  In particular, the path /article/by-id is not matched against Article, even though it would succeed. The parser looks for constant fragments, and if none corresponds, it looks for field fragments; but once it has chosen one of these branches, it does not backtrack.

  Question: is the above a good design? Or should paths that correspond to a constant fragment but fail to match the rest of the pattern be tried against field fragments?

  A common prefix should also be able to include a field. For example:

  type CommonFieldPrefix =
      | [<EndPoint "/user/{id}/followers">] Followers of id: string
      | [<EndPoint "/user/{id}/likes">]     Likes of id: string

  The field name is of course irrelevant and doesn't have to be the same.

  Question: what should happen if two endpoints have a common prefix up to a field with different types? eg:

  type DifferentTypeFieldPrefix =
      | [<EndPoint "/user/{id}/followers">] Followers of id: string
      | [<EndPoint "/user/{id}/likes">]     Likes of id: int

  • Option 1: it's an error. I think this is more consistent and less error prone.
  • Option 2: they're tried in the order in which the cases are declared.

Possible extensions:

• {*field} to catch the rest of the path, of type string, list<_> or array<_>. It must be unique and at the end of the path.

• {?field} for optional fields, of type option<_>. They must all be at the end of the path, before {*field} if any.

• Some form of handling for query parameters. Possible syntax:

  type WithQuery =
      | [<EndPoint "/article/{id}?page={page}&tags={?t}">]
        Article of id: int * page: int * t: option<string>