Run Your Application section ... ???

[LappleApple]

Hi,

This section is confusing me: https://github.com/zalando/api-first-hand#run-your-application. -- How does it relate to the https://github.com/zalando/api-first-hand#building-an-api-first-hand-plugin section? -- "Before we go any further, let's run the application" (Ln 123). Which application? The previous section "Tutorial" isn't really one; in my revision (https://github.com/LappleApple/api-first-hand/blob/master/README.md) I remove this section completely but I've saved that little bit of code. (I'm not clear on whether that code should truly reside.) -- "The service template comes with the Swagger UI frontend included, run statically from the within Play, which provides a sandbox for your service" (Lns 129-130). What service template? It's not mentioned in the previous section, which lists some of the Template contents. -- "The template is configured with a template Swagger API definition called example.yaml and located in the conf directory of the Play application...." this + rest of this section is framed as descriptive info. When I see a section called "Run Your Application" I expect steps and directions. So let's rework this a bit: -- "This definition contains three end points: " there are only two bullet points. And then there are two APIs mentioned (GET /token API and POST /token API, plus the GET /todos/{user_id}. It's not clear to me if GET /todos/{user_id} is another API, or the third endpoint. Can you clarify? -- "The token can be requested using the Swagger UI." Can we rewrite as: "use the marshaller for OAuth2 tokens, security/example.yaml.scala, to request an OAuth token with the scope admin:org; this is necessary for the client to be able to access this endpoint." -- "Click the default button to expand the API definition in the Swagger UI." This is the only remaining/last step in the section. Are we missing any steps in between? I'm sure the endpoints/tokens info above => those steps and this will become clearer once we convert that info into true steps.

[LappleApple]

@slavaschmidt Wondering if you can help out here; I'd like to get the README revised today to start promoting it again. :)

[slavaschmidt]

@LappleApple Sorry, totally under load until 16th of March

[LappleApple]

Thanks, @slavaschmidt. @stuartmclean @s12v @gipeshka Hey, maybe one of you can help me out? I think I get it, but want to make sure ...

[slavaschmidt]

Hi, here some thoughts:

-- How does it relate to the https://github.com/zalando/api-first-hand#building-an-api-first-hand-plugin section?

The section 'Run your application' does not relate to the section 'Building an Api-First-Hand Plugin'. The first one is for plugin users, the second one is for plugin developers.

-- "Before we go any further, let's run the application" (Ln 123). Which application? The previous section "Tutorial" isn't really one; in my revision (https://github.com/LappleApple/api-first-hand/blob/master/README.md) I remove this section completely but I've saved that little bit of code. (I'm not clear on whether that code should truly reside.)

The logical flow is as following: the second line of the tutorial part shows hot to use an activator template. if executed, it creates a folder on the local machine. Then there is a description of what this folder contains. Then the user literally can run the application she has just created.

-- "The service template comes with the Swagger UI frontend included, run statically from the within Play, which provides a sandbox for your service" (Lns 129-130). What service template? It's not mentioned in the previous section, which lists some of the Template contents.

It's like "The plugin provides a template for your REST service. This templates includes swagger UI like here http://petstore.swagger.io embedded into the service itself"

-- "The template is configured with a template Swagger API definition called example.yaml and located in the conf directory of the Play application...." this + rest of this section is framed as descriptive info. When I see a section called "Run Your Application" I expect steps and directions. So let's rework this a bit:

These are steps needed to run the application:

Open a shell and cd into your service project directory.
Start sbt and run the service.
View the running application at http://localhost:9000.

-- "This definition contains three end points: " there are only two bullet points. And then there are two APIs mentioned (GET /token API and POST /token API, plus the GET /todos/{user_id}. It's not clear to me if GET /todos/{user_id} is another API, or the third endpoint. Can you clarify?

A single specification defines a single API. In our case these are 3 three endpoints of the API:

1. GET /token
2. POST /token
3. GET /todos/{user_id}

-- "The token can be requested using the Swagger UI." Can we rewrite as: "use the marshaller for OAuth2 tokens, security/example.yaml.scala, to request an OAuth token with the scope admin:org; this is necessary for the client to be able to access this endpoint."

Yeah, if one is testing the API, he needs a token which can be used with the Swagger UI. The phrase relates to this describing that the token can be requested using the same UI

-- "Click the default button to expand the API definition in the Swagger UI." This is the only remaining/last step in the section. Are we missing any steps in between? I'm sure the endpoints/tokens info above => those steps and this will become clearer once we convert that info into true steps.

This section is supposed to make one comfortable with the Swagger UI. After that the user is expected to start changing the specification or write some backend-code and use the Swagger UI to see the results.

Hope this helps :)

[LappleApple]

Hey @slavaschmidt, I took your suggestions and implemented them here: https://github.com/LappleApple/api-first-hand/blob/master/README.md#getting-started-with-api-first-hand. Does my order make sense?

I'm wondering also about this section: https://github.com/LappleApple/api-first-hand/blob/master/README.md#about-api-first-hand-architecture-and-structure

From you other comments, it seems that the audience for this latter section is people who want to develop the plugin (as contributors). Is that correct? I'm wondering about the audience for this section because we can either target those potential contributors, or "advanced-level users" of the plugin. Or perhaps the section should suggest something about "additional features."

[LappleApple]

Also, this was a little confusing: "To build a plugin, do the following:" ... because the project is a plugin. Are we creating plugins of the plugin? :)

[slavaschmidt]

Also, this was a little confusing: "To build a plugin, do the following:" ... because the project is a plugin. Are we creating plugins of the plugin? :)

+1, better would be "to build a plugin from sources, do the following" as opposed to use it as an artefact

[LappleApple]

@slavaschmidt agreed, that makes it so much better!

PS: But wait. :) It's still a little confusing because it suggests that you will build a brand-new plugin, when you .... are not, right? Because this project is a plugin.

[alexkops]

Are we creating plugins of the plugin?

[slavaschmidt]

there are plugins all the way down 👍 @alexkops, on a serious note, we have pluggable specification parsers and pluggable artefact generators :)

[LappleApple]

@slavaschmidt that clears some things up! So ... can you point me to exactly where that helpful language -- "pluggable specification parsers and pluggable artefact generators" -- can go in the revised README? :)

[slavaschmidt]

@LappleApple please give me some time to carefully read the revised README :). But i'm not sure that I'll get that before the weekend, sorry

[slavaschmidt]

can you point me to exactly where that helpful language -- "pluggable specification parsers and pluggable artefact generators" -- can go in the revised README?

I'd put it into the beginning of the Plugin Architecture section https://github.com/zalando/api-first-hand/blob/master/README.md#plugin-architecture

[LappleApple]

@slavaschmidt +1, made that change. Thanks!