spec: allow named endpoints #198

LinusU · 2015-05-26T07:09:17Z

See discussion in #196

zdne · 2015-05-27T12:05:09Z

When I think about it more conceptually – the endpoint as such is actually an action section in API Blueprint parlance (albeit it implies a new resource). Therefore it should be defined under Action and not resource as such.

This, however, has some implications – suddenly we can have "action" section at the top of a blueprint so the "Blueprint document structure" needs to be updated accordingly.

Internally, in the parser, this should be still picked up by Resource parser as it essentially creates a new resource (in AST) but this is opaque to user.

Furthermore parser should not warn when an action with the same URI template (but different method) is described, instead, it should add it under the respective resource.

Overall as simply as it looks it is actually quite complex problem :)

LinusU · 2015-05-27T12:57:47Z

Hmm, I guess that in that case we'd want to change the behaviour of # GET /e1 as well, no?

I'm not sure if I'm happy with letting content "jump" to different places thought, it would make the internals quite a bit more complicated?

It would also make it complicated to do "guides" with blueprint since the content might not necessarily come in the order that you specify it in the markdown.

e.g.

# Create a user [POST /users]

...

# Log in as the user [POST /sessions]

...

# List all users [GET /users]

...

This would now list List all users before it listed Log in as the user making that call fail...

pksunkara · 2015-05-28T14:51:22Z

examples/13. Named Endpoints.md

+
+ Request
+  + Headers
+    Content-Type: application/json


The content inside Headers and Body list items should be code blocks. So, indent them by 12 spaces.

pksunkara · 2015-05-28T15:04:23Z

A few styling issues other than looks good. But I agree with @zdne that even though this issue looks simple, it is a bit complex one. We need to do some thinking on this.

pksunkara · 2015-05-31T08:19:56Z

API Blueprint Specification.md

+
+Defined by a resource [name (identifier)](#def-identifier) followed by an [HTTP request method][httpmethods] and an [URI template][uritemplate] enclosed in square brackets `[]`:
+
+    # <identifier> [<HTTP request method> <URI template>]


By the way, if we are doing this, please add some info about this to the section title Header Keywords.

@pksunkara I think it is OK to leave it as it is, because it is being already covered by "Combinations of an HTTP method and URI Template (e.g. GET /resource/{id})"

zdne · 2015-06-01T08:43:01Z

Hey @LinusU I was thinking about it a bit more and I think you are indeed right with:

I guess that in that case we'd want to change the behaviour of # GET /e1 as well, no?

Now doing that and also addressing

the content might not necessarily come in the order that you specify it in the markdown.

is quite radical change... So lets recap on what are the options:

1. Add name to an endpoint

Simply allow adding a name to # <HTTP request method> <URI template> action and leave everything else as is.

Pros

simplest way to add a name
doesn't change current behavior

Cons

everything stays under one resource - you will loose the order of these "named endpoints" in the case when they are hitting the same URI

2. Separate endpoints from resources

Introduce a new top-level "endpoint" section – for # <HTTP request method> <URI template> or # <Name> [<HTTP request method> <URI template>].

Pros

maintain order of endpoints
clearly distinguish between resource and endpoint architecture (or document structure)

Cons

need to change AST
changing behavior of existing things
much more complex on implementation side
affects all the tools

Thoughts ?

LinusU · 2015-06-02T12:10:48Z

@zdne great writeup.

Number 1 is what I have implemented in this pull request, the only change really is to allow a name to the resource that gets generated.

I do like number 2 quite much thought, but as you say it's much more work involved. I think that we need to clarify a bit an endpoint is. Is it a path (e.g. /cars) or a method + path (e.g. GET /cars)? Would an endpoint contain an action? Or maybe any number of action? Or is the endpoint in itself an action?

If we try and work our way from the ast, which I think is a good approach, how would the new ast structure look?

I guess that it looks something like this currently:

category root
- resource
  - action
- category
  - resource
    - action

And it would become something like this if we added endpoints:

category root
- endpoint
- resource
  - action
- category
  - endpoint
  - resource
    - action

Or maybe resource really just should be a category and action should be an endpoint. The uri would than be moved and placed in every endpoint instead of the one resource.

category root
- endpoint
- category
  - endpoint

Very simple ast at least. Every endpoint should then contain uriTemplate and method.

Maybe a good approach would be to implement number 1 now since that dosen't change anything for the existing ecosystem, and then try and figure out what we think about number 2.

I really like the ideas in number 2 thought, it makes it possible to specify APIs that aren't RESTful which I think is important.

zdne · 2015-06-04T08:47:59Z

@LinusU OK so let's break it into two parts

Just adding names to top-level method + URI pairs
Changing the internals to reflect ordering

zdne · 2015-06-04T08:53:16Z

I think that we need to clarify a bit an endpoint is.

👍

In the current context I am using the term "endpoint" for a method + URI pair

it makes it possible to specify APIs that aren't RESTful which I think is important.

👍

Note @smizell is currently working Refract Resource Namespace – this eventually should be the underlaying data structure – I believe he will address these main concept there (resources and transition) using some sort of recursive pattern.

TL;DR let's figure this one (point 2 as mentioned above) in the Resource namespace first and focus on just adding names to currently un-named method URI pairs.

Sounds good?

zdne · 2015-06-04T08:57:10Z

examples/13. Named Endpoints.md

+  + Headers
+    Content-Type: application/json
+  + Body
+    { "username": "Linus", "password": "test" }


Consistence: Can we please use the same / similar example data as in the previous examples?

zdne · 2015-06-04T08:59:19Z

@LinusU Please address the review comments on the example and it is good to go! Thanks! 🎈

LinusU · 2015-06-05T07:35:47Z

@zdne Should be good to go 👍

pksunkara · 2015-06-05T08:39:05Z

API Blueprint Specification.md

+
+    # <identifier> [<HTTP request method> <URI template>]
+
+> **NOTE:** In the two latter cases the rest of this section represents the [Action section](#def-action-section) including its description and nested sections and **follows the rules of Action section instead**.


- In the two latter + In the latter two

LinusU · 2015-06-05T08:45:09Z

@pksunkara Done!

pksunkara · 2015-06-05T09:11:24Z

Looks good. I am toggling this as "Passed Review". 👍

pksunkara · 2015-06-05T09:15:16Z

@zdne Since I merged apiaryio/snowcrash#332, Do we merge this? Or should we wait for releasing it on Apiary?

zdne · 2015-06-05T09:24:29Z

@pksunkara I think we can merge this / update README (version supported in apiary) and release new version of API Blueprint...

pksunkara · 2015-06-05T15:26:45Z

@LinusU Can you please make a new commit to this PR updating the current format to 1A9 from 1A8? Thanks.

LinusU · 2015-06-08T07:40:55Z

I'm on it!

LinusU · 2015-06-08T07:49:45Z

Done, I did not tag it since it seems that you have always tagged the merge commit :)

spec: allow named endpoints

LinusU · 2015-06-08T07:53:18Z

Cheers 🍻

spec: allow named endpoints

19d7224

LinusU mentioned this pull request May 26, 2015

question: does dredd support chain-calls (testing flows)? apiaryio/dredd#151

Closed

pksunkara reviewed May 28, 2015
View reviewed changes

pksunkara reviewed May 31, 2015
View reviewed changes

zdne mentioned this pull request Jun 2, 2015

Duplicate resource URLs not handled #203

Closed

zdne added type (2): Feature PR: Do not merge labels Jun 3, 2015

zdne reviewed Jun 4, 2015
View reviewed changes

LinusU force-pushed the patch-1 branch from 08698db to f658218 Compare June 5, 2015 07:35

pksunkara reviewed Jun 5, 2015
View reviewed changes

example: named endpoints

a16b1ba

LinusU force-pushed the patch-1 branch from f658218 to a16b1ba Compare June 5, 2015 08:44

pksunkara added PR: Passed Review and removed PR: Do not merge labels Jun 5, 2015

Increment API Blueprint version to 1A9

57cd495

pksunkara added a commit that referenced this pull request Jun 8, 2015

Merge pull request #198 from LinusU/patch-1

d204824

spec: allow named endpoints

pksunkara merged commit d204824 into apiaryio:master Jun 8, 2015

LinusU deleted the patch-1 branch June 8, 2015 07:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

spec: allow named endpoints #198

spec: allow named endpoints #198

LinusU commented May 26, 2015

zdne commented May 27, 2015

LinusU commented May 27, 2015

pksunkara May 28, 2015

zdne Jun 4, 2015

pksunkara commented May 28, 2015

pksunkara May 31, 2015

zdne Jun 4, 2015

zdne commented Jun 1, 2015

LinusU commented Jun 2, 2015

zdne commented Jun 4, 2015

zdne commented Jun 4, 2015

zdne Jun 4, 2015

zdne commented Jun 4, 2015

LinusU commented Jun 5, 2015

pksunkara Jun 5, 2015

LinusU commented Jun 5, 2015

pksunkara commented Jun 5, 2015

pksunkara commented Jun 5, 2015

zdne commented Jun 5, 2015

pksunkara commented Jun 5, 2015

LinusU commented Jun 8, 2015

LinusU commented Jun 8, 2015

LinusU commented Jun 8, 2015


		Defined by a resource [name (identifier)](#def-identifier) followed by an [HTTP request method][httpmethods] and an [URI template][uritemplate] enclosed in square brackets `[]`:

		# <identifier> [<HTTP request method> <URI template>]


		# <identifier> [<HTTP request method> <URI template>]

		> NOTE: In the two latter cases the rest of this section represents the [Action section](#def-action-section) including its description and nested sections and follows the rules of Action section instead.

spec: allow named endpoints #198

spec: allow named endpoints #198

Conversation

LinusU commented May 26, 2015

zdne commented May 27, 2015

LinusU commented May 27, 2015

pksunkara May 28, 2015

Choose a reason for hiding this comment

zdne Jun 4, 2015

Choose a reason for hiding this comment

pksunkara commented May 28, 2015

pksunkara May 31, 2015

Choose a reason for hiding this comment

zdne Jun 4, 2015

Choose a reason for hiding this comment

zdne commented Jun 1, 2015

1. Add name to an endpoint

Pros

Cons

2. Separate endpoints from resources

Pros

Cons

LinusU commented Jun 2, 2015

zdne commented Jun 4, 2015

zdne commented Jun 4, 2015

zdne Jun 4, 2015

Choose a reason for hiding this comment

zdne commented Jun 4, 2015

LinusU commented Jun 5, 2015

pksunkara Jun 5, 2015

Choose a reason for hiding this comment

LinusU commented Jun 5, 2015

pksunkara commented Jun 5, 2015

pksunkara commented Jun 5, 2015

zdne commented Jun 5, 2015

pksunkara commented Jun 5, 2015

LinusU commented Jun 8, 2015

LinusU commented Jun 8, 2015

LinusU commented Jun 8, 2015