[Spike] Give bottom-up examples in Controllers.md, Routes.md, Repositories.md and Decorators.md

[shimks]

Description / Steps to reproduce / Feature proposal

• The four docs in the title all use the api-first approach of wiring the routing in RestServer; very often in these docs, an OpenApi fragment is defined first and then registered instead of having it automatically generated.
  • http://loopback.io/doc/en/lb4/Controllers.html
  • http://loopback.io/doc/en/lb4/Routes.html
  • http://loopback.io/doc/en/lb4/Repositories.html
  • http://loopback.io/doc/en/lb4/Decorators.html
• The content of these pages should be tweaked so that it advocates for our recommended bottom-up approach

Acceptance Criteria

• For the docs Controllers, Routes, Repositories, and Decorators
  • Replace top-down approach code (starting out with a complete spec) with an equivalent bottom-up (via the use of automatic-inference decorators like @get)
  • If there are already examples of bottom-up code that demonstrates how the artifacts are being used (potentially in Controllers and Decorators), simply delete the top-down example and bring up the bottom-up example in its place delete or move them to a less invisible place(case by case)

Quick spike

• controllers
  • Routing to controllers: create route by providing a complete spec instead of using rest decorator. Move it to bottom, declare we don't fully support it yet.
  • Specify controller APIs same as above ^
• routes
  • Creating rest routes, there are 3 approaches for creating routes, the first 2 are top-down. Move the 3rd one(using decorator) up to be the first, move the other twos to the bottom, declare we don't fully support it yet.
• repositories
  • defining crud methods for your application, out of date, replace the content with the new approaches using decorators.
• decorators
  • api decorator, move it to the bottom and declare that it's not fully supported yet.

See Reporting Issues for more tips on writing good issues

[bajtos]

AFAICT, Controllers describe code-first approach too, see http://loopback.io/doc/en/lb4/Controllers.html#writing-controller-methods.

Having said that, I agree the page may need some reorganization to increase visibility of the code-first approach and decrease visibility of the design-first approach.

Similar comment applies to Decorators too - we have examples showing code-first approach, see e.g. http://loopback.io/doc/en/lb4/Decorators.html#operation-decorator.

[dhmlau]

I'm thinking that the code snippets shown in our documentation can be more coherent. For example, if the todo example contains most of the code we need, maybe it's a good idea to reference the code in there, i.e. copy the code snippet over and mention to users the location of a complete example can be found.

Another advantage of doing this is we do not need to spend significant amount of time to validate the code snippet for each doc, as long as we've tested the todo example (for example) is good.

[bajtos]

We should have a tutorial showing how to build applications bottom-up way. @raymondfeng could you please add more details about what such tutorial should include? We already have Todo example, what do we need to change or add to make that example good enough as the tutorial?

[raymondfeng]

I suggest that we create a tutorial following the narratives below:

1. Define a controller class to describe the business functions to be exposed as REST APIs
2. Add decorators to controller methods to map to REST endpoints
3. Introduce a Todo model to represent the business object
4. Introduce a TodoRepository for persistence
5. Configure the TodoRepository with a DataSource to a database
6. Use dependency injection to wire all things up

[bajtos]

I suggest that we create a tutorial following the narratives below (etc.)

With the exception of the second step (add decorators to controller methods), such tutorial is already available in the top-down version here: http://loopback.io/doc/en/lb4/Implementing-features.html

We could copy that page and rework it to show bottom-up approach, but then we would end up with a lot of duplicated content.

For long term, I think we need to find a way how to show both top-down and bottom-up approaches in a way that allows us to keep shared sections in a single place.

In DP3, top-down approach is out of scope, therefore we don't need the current content in Implementing-features. I am proposing to rework that page to use bottom-up approach and maybe change it's style so that the page reads more like a tutorial than a best-practice guide.

Thoughts?

[jannyHou]

Let's keep discussion and revisit it in the next meeting.

[jannyHou]

@raymondfeng based on your comment:

I suggest that we create a tutorial following the narratives below:

1. Define a controller class to describe the business functions to be exposed as REST APIs
2. Add decorators to controller methods to map to REST endpoints
3. Introduce a `Todo` model to represent the business object
4. Introduce a `TodoRepository` for persistence
5. Configure the `TodoRepository` with a `DataSource` to a database
6. Use dependency injection to wire all things up

Do you want a new tutorial that following exactly the order from 1 to 6, meaning define controller first then the model and repository, or the order of creating artifacts doesn't matter?

If ignoring the order, I think we already have such a tutorial called "Todo Tutorial": http://loopback.io/doc/en/lb4/todo-tutorial.html

Is it the ideal tutorial for you?

[jannyHou]

Hi team @strongloop/sq-lb-apex @raymondfeng @bajtos @hacksparrow , after following the conversation above, I think we at least agree on make the api first approach(top-down) less visible in the 4 documentation pages list in #1173 (comment).

I would also suggest we don't document a concept in a way that the code first and api first approaches are mixed, they can be on the same page, but in two separate sections, so readers can consistently follow the supported approach to build their code, and read more about the other approach if they are interested.

Based on the current acceptance criteria, I would suggest modify it to

For the docs Controllers, Routes, Repositories, and Decorators

• Use code first(bottom-up) approach to build app across all concepts/artifacts
  • If the document is already written in that way, keep it
  • If the document has api first approach(top-down), replace it with the code first example(via the use of automatic-inference decorators like @get).
• If there are already examples of bottom-up code that demonstrates how the artifacts are being used (potentially in Controllers and Decorators), move them to a more visible section.
  • Do our best to reduce the duplicate code

Thought?

[bajtos]

If there are already examples of bottom-up code that demonstrates how the artifacts are being used (potentially in Controllers and Decorators), move them to a less visible section.

I think you meant top-down code examples should be moved to less visible sections?

The proposal looks good to me. To be honest, I think it would be more effective to sandbox this task to a certain amount of time and let the person working on the task to decide what's best, rather than spend so much time and effort on coming up with clear acceptance criteria.

[jannyHou]

From last estimation meeting:
Let's do a quick spike:

• Take a look of the 4 pages in story description, list the sections
  • out of date, need to remove
  • out of date, need to replace

[jannyHou]

• controllers
  • Routing to controllers: create route by providing a complete spec instead of using rest decorator. Move it to bottom, declare we don't fully support it yet.
  • Specify controller APIs same as above ^
• routes
  • Creating rest routes, there are 3 approaches for creating routes, the first 2 are top-down. Move the 3rd one(using decorator) up to be the first, move the other twos to the bottom, declare we don't fully support it yet.
• repositories
  • defining crud methods for your application, out of date, replace the content with the new approaches using decorators.
• decorators
  • api decorator, move it to the bottom and declare that it's not fully supported yet.

I agree with @bajtos in comment #1173 (comment), while a quick spike would also give the story owner a much clear scope, so I did the quick spike as we discussed last time.
cc @strongloop/sq-lb-apex @hacksparrow @raymondfeng @bajtos

[dhmlau]

@jannyHou , so your above comment is the acceptance criteria of this task?

[dhmlau]

#1512 #1513 #1514 #1515 are created as the outcome of the spike.
closing this spike as done.