#/definitions/article/links/1/href: failed schema

[JulienPalard]

Hi,

I'm getting a:

unverified_schema.json: #/definitions/article/links/1/href: failed schema #/definitions/resourceLink/properties/href: /articles/ does not match /^(\/((?!-|_)[a-z0-9_\-]+(?<!-|_)|\{\(.*\)\}))+$/.

Which is true, I have a:

{
    "description": "List some articles.",
    "href": "/articles/",
    "method": "GET",
    "rel": "instances",
    "targetSchema": {
        "$ref": "/schemata/article#/definitions/list_of_article"
    },
    "title": "Article list"
}

Which looks right to me, listing articles (a collection, a direcrory of articles) is at "/articles/", not at "/article" (which means a file, which is different from a collection of files), linking to articles with URLs like "/articles/1234" ("files").

Why does URI with a trailing are forbidden ? They look right to me, can you allow it in the URL regex ?

[geemus]

I think this may just be a consistency thing. Having an href there of either /articles/ or /articles should be equivalent in usage, so just trying to make sure it is consistently the shorter/simpler version doesn't seem so bad. Does that help/make sense?

[JulienPalard]

Hi,

Having an href there of either /articles/ or /articles should be equivalent in usage

If equivalent in usage, they still can be considered semantically different:

I like to see a REST API as as simple HTTP server serving files, so, for me: "/articles/" is a directory (a collection), and "/article" is a file which does not exists. "/articles/1" is a file which exists, and "/articles/1/" is a directory which does not exists.

From my very personal point of view, a REST API is not just bytes flowing on networks (the usage), it should me meaningfull, it should expose resouces in an expressive and semantical way, and here, trailing slash helps me being explicit and expressive (for the users).

I know there's an infinitely long debate here, let's not start another (Woops, I started, I'm very sorry, and not proud):

• Having a trailing slash like "/article/" permits relative URI like "1" to resolve to "/articles/1/" which is NOT to case with "/article" in which a URI like "1" resolve to "/1" which does not exists.
• https://en.wikipedia.org/wiki/Representational_state_transfer#Example examples with "/" being collections and without "/" being collection members
• Some blog (yeark) speaking about trailing slashes : https://cdivilly.wordpress.com/2014/03/11/why-trailing-slashes-on-uris-are-important/
• I don't want to redirect "not slash" to "slash": that's a useless redirection the developper could have fixed upfront hitting a violent 404, avoiding de facto a huge number of very useless 301/302 in production (useless round-trips, useless increased load times ....)

But I know it's controversial:

• https://github.com/nicolaiarocci/eve/issues/118
• I don't remember seeing any reference to this in the Fielding thesis
• http://masnun.com/2013/09/18/django-rest-framework-angularjs-resource-trailing-slash-problem.html

Very controversial:

• if /users/ is a collection of users (a directory)
• and /users/1 is a user (a file)
• but /users/1/posts/ is a collection of the 1st user posts
• WTF did I just said ? A file having a directory in it ?

Yet ... the API I'm writing HyperSchema for already exists, obviously can't be changed, is already documented and used with the philosophy "trailing slash means collection". Does the existence of a debate, even with more people against it that agreeing on it, should prohibe us to documents this API ?

So if you're definitely on the "no trailing /" side, a warning should be more appropriate than a "throw exception and exit" here ?

[geemus]

Fair point, I'd never really thought about/worried about it very deeply to be honest (hence my comment about interchangeability), for me they were roughly equivalent and in cases where there are equivalences I like to just pick one and stick with it. That said, I still don't feel particularly strongly about this one way or another, I'm amenable to allowing the trailing slash, would you be up for making a pull request to loosen the expectation? Thanks!