From 0a2555f7b2e324eadf753a1e81d08e3571e3af24 Mon Sep 17 00:00:00 2001 From: shimks Date: Fri, 16 Feb 2018 22:36:28 -0500 Subject: [PATCH 1/7] add best practices for bottom up --- _data/sidebars/lb4_sidebar.yml | 13 +- .../en/lb4/Best-practices-with-Loopback-4.md | 12 +- ...fining-the-API-using-bottom-up-approach.md | 156 ++++++++++++++++++ ...fining-the-API-using-top-down-approach.md} | 12 +- .../en/lb4/Defining-your-testing-strategy.md | 2 +- pages/en/lb4/Examples-and-tutorials.md | 3 +- pages/en/lb4/Testing-the-API.md | 2 +- users/index.html | 3 +- 8 files changed, 187 insertions(+), 16 deletions(-) create mode 100644 pages/en/lb4/Defining-the-API-using-bottom-up-approach.md rename pages/en/lb4/{Defining-and-validating-the-API.md => Defining-the-API-using-top-down-approach.md} (96%) diff --git a/_data/sidebars/lb4_sidebar.yml b/_data/sidebars/lb4_sidebar.yml index 9f463b32d..21cd85351 100644 --- a/_data/sidebars/lb4_sidebar.yml +++ b/_data/sidebars/lb4_sidebar.yml @@ -111,13 +111,18 @@ children: output: 'web, pdf' children: - - title: 'Defining and validating the API' - url: Defining-and-validating-the-API.html + - title: 'Defining the API using bottom-up approach' + url: Defining-the-API-using-bottom-up-approach.html output: 'web, pdf' - - title: 'Testing the API' - url: Testing-the-API.html + - title: 'Defining the API using top-down approach' + url: Defining-the-API-using-top-down-approach.html output: 'web, pdf' + children: + + - title: 'Testing the API' + url: Testing-the-API.html + output: 'web, pdf' - title: 'Defining your testing strategy' url: Defining-your-testing-strategy.html diff --git a/pages/en/lb4/Best-practices-with-Loopback-4.md b/pages/en/lb4/Best-practices-with-Loopback-4.md index 6ec16bcef..76954faf6 100644 --- a/pages/en/lb4/Best-practices-with-Loopback-4.md +++ b/pages/en/lb4/Best-practices-with-Loopback-4.md @@ -12,8 +12,10 @@ LoopBack 4 is more than just a framework: It’s an ecosystem that encourages de Our best practice follows an "API first" and test-driven development approach: -1. [**Defining and validating the API**](./Defining-and-validating-the-API.html): This section guides you through constructing your API first before any internal logic is added. -2. [**Testing the API**](./Testing-the-API.html): This section describes the process of writing smoke test for your API and its spec. -3. [**Defining your testing strategy**](./Defining-your-testing-strategy.html): This section discusses the advantages and the process of building a strong testing suite. -4. [**Implementing features**](./Implementing-features.html): This section demonstrates how the tests for each feature of your application should be written, and how to write the logic to make these tests pass. In the example, the tests for the controller, model, repository, data source, and sequence are written and then implemented. -5. [**Preparing the API for consumption**](./Preparing-the-API-for-consumption.html): This section shows how the endpoints can be physically tested using the Swagger UI. +1. **Defining the API**: There are two possible approaches to take in this section + - [**Defining the API using bottom-up appraoch**](./Defining-the-API-using-bottom-up-approach.html): This section guides you through setting up a skeleton of your application so that a full API can be automatically generated. + - [**Defining the API using top-down approach**](./Defining-the-API-using-top-down-approach.html): This section guides you through constructing your API first before any internal logic is added. + - [**Testing the API**](./Testing-the-API.html): This section describes the process of writing smoke test for your API and its spec. +2. [**Defining your testing strategy**](./Defining-your-testing-strategy.html): This section discusses the advantages and the process of building a strong testing suite. +3. [**Implementing features**](./Implementing-features.html): This section demonstrates how the tests for each feature of your application should be written, and how to write the logic to make these tests pass. In the example, the tests for the controller, model, repository, data source, and sequence are written and then implemented. +4. [**Preparing the API for consumption**](./Preparing-the-API-for-consumption.html): This section shows how the endpoints can be physically tested using the Swagger UI. diff --git a/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md b/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md new file mode 100644 index 000000000..ab5177ef0 --- /dev/null +++ b/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md @@ -0,0 +1,156 @@ +--- +lang: en +title: 'Defining the API using bottom up approach' +keywords: LoopBack 4.0, LoopBack 4 +tags: +sidebar: lb4_sidebar +permalink: /doc/en/lb4/Defining-the-API-using-bottom-up-approach.html +summary: +--- + +## Define the API from bottom to top + +### Start with LoopBack artfiacts + +Sometimes, it's hard to know what your API is going to look like without +writing out your application first. It also might be difficult to adjust your +API as plans change or as features need to be reworked. + +With TypeScript's [experimental decorator](https://www.typescriptlang.org/docs/handbook/decorators.html) +feature, APIs can be automatically built and exposed as your application +continues development. Some key concepts utilize decorators to gather +'metadata' about your code and then assemble them into a valid OpenAPI spec. +These concepts and their decorators include: + +- [Model](Model.html) + - `@model()` + - `@property()` +- [Routes](Routes.html) + - `@operation()` + - `@param()` + +### Define your models + +Your models will be used to provide schemas to validate against the data +your API will intercept and consequently are likely to be referenced as +argument types in your controllers, so they should be the first to be defined. + +{% include note.html content=" + `Todo` model from [tutorial](TUTORIAL LINK) is used for demonstration here. +" %} + +First, write a simple TypeScript class describing your model and its +properties. + +```ts +export class Todo { + id?: number; + title: string; + desc?: string; + isComplete: boolean; +} +``` + +This model is just a TypeScript class without any decorators in its current +form, so features such as automatic schema generation are not available to it +yet. + +Now decorate the class with `@model` and `@property`. + +```ts +import {model, property} from '@loopback/repository'; + +@model() +export class Todo { + @property() id?: number; + @property({ + required: true + }) + title: string; + @property() desc?: string; + @property() isComplete: boolean; +} +``` + +Once the model has been decorated with these decorators, +its metadata is made available to the app and the model is ready to have its +corresponding OpenAPI schema generated. + +### Define your routes + +{% include note.html content=" + `TodoController` from [tutorial](TUTORIAL LINK) is used for + demonstration here. +" %} + +Once your models are defined, create a controller to host your routes +for each categories of your API. + +```ts +class TodoController { + constructor() {} + + async createTodo(todo: Todo) { + // data creating logic goes here + } + + async findTodoById(id: number, items?: boolean): Promise { + // data retrieving logic goes here + } + + // ... +} +``` + +The controller's routes in their current state has no information on which +API endpoints they belong to. Add them in by using `@operation` and `@param` +decorators. + +```ts +class TodoController { + constructor() {} + + @post('/todo') // sugar for @operation('post', '/todo'); + async createTodo(@param.body('todo') todo: Todo) { + // data creating logic goes here + } + + @get('/todo/{id}') + async findTodoById( + @param.path.number('id') id: number, + @param.query.boolean('items') items?: boolean + ): Promise { + // data retrieving logic goes here + } + + // ... +} +``` + +Once your routes have been decorated, your application is ready to serve +its API; when an instance of `RestServer` is run, an OpenAPI specification +representing your application's API is built. The spec is generated +entirely from the decorated elements' metadata, which in turn provides +routing logic for your API when your application is running. + +### Reviewing your API specification + +To review your complete API specification, run your application with the +decorated controllers registered. Once it is running, visit `/swagger.json` +endpoint to see your API specification. Alternatively, the specification file +can also be accessed in code through the `getApiSpec()` function from your +`RestServer` instance. + +For a complete walkthrough of developing an application with the bottom-up +approach, see our [Todo application](LINK TO TUTORIAL) +tutorial. + +{% include note.html content=" + If you would like to create your API manually or already have one designed, + refer to [Defining the API using top-down approach](Defining-the-API-using-top-down-approach) + page for best practices. +" %} + +{% include next.html content= " +[Defining your testing strategy](./Defining-your-testing-strategy.html) +" %} diff --git a/pages/en/lb4/Defining-and-validating-the-API.md b/pages/en/lb4/Defining-the-API-using-top-down-approach.md similarity index 96% rename from pages/en/lb4/Defining-and-validating-the-API.md rename to pages/en/lb4/Defining-the-API-using-top-down-approach.md index 65cb22be7..7d0e654d1 100644 --- a/pages/en/lb4/Defining-and-validating-the-API.md +++ b/pages/en/lb4/Defining-the-API-using-top-down-approach.md @@ -1,10 +1,10 @@ --- lang: en -title: 'Defining and validating the API' +title: 'Defining the API using top-down approach' keywords: LoopBack 4.0, LoopBack 4 tags: sidebar: lb4_sidebar -permalink: /doc/en/lb4/Defining-and-validating-the-API.html +permalink: /doc/en/lb4/Defining-the-API-using-top-down-approach.html summary: --- {% include important.html content="The top-down approach for building LoopBack @@ -13,7 +13,7 @@ page are outdated and may not work out of the box. They will be revisited after our MVP release. "%} -## Define the API +## Define the API from top to bottom ### Start with data @@ -352,6 +352,12 @@ describe('API specification', () => { See [Validate your OpenAPI specification](Testing-your-application.html#validate-your-openapi-specification) from [Testing your application](Testing-your-application.html) for more details. +{% include note.html content=" + If you would like to make tweaks to your API as you develop your application, + refer to [Defining the API using bottom-up approach](Defining-the-API-using-bottom-up-approach) + page for best practices. +" %} + {% include next.html content= " [Testing the API](./Testing-the-API.html) " %} \ No newline at end of file diff --git a/pages/en/lb4/Defining-your-testing-strategy.md b/pages/en/lb4/Defining-your-testing-strategy.md index 8ad7f49a5..98d232ec7 100644 --- a/pages/en/lb4/Defining-your-testing-strategy.md +++ b/pages/en/lb4/Defining-your-testing-strategy.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues off from [Testing the API](./Testing-the-API.html). +This article continues off from [Testing the API](./Testing-the-API.html) and [Defining the API using bottom-up approach](./Defining-the-API-using-bottom-up-approach.html). " %} ## Define your testing strategy diff --git a/pages/en/lb4/Examples-and-tutorials.md b/pages/en/lb4/Examples-and-tutorials.md index ab4594474..1854b82f8 100644 --- a/pages/en/lb4/Examples-and-tutorials.md +++ b/pages/en/lb4/Examples-and-tutorials.md @@ -14,7 +14,8 @@ LoopBack 4 comes with the following example projects: Tutorial on setting up a simple hello-world application using LoopBack 4. - **[getting-started](https://github.com/strongloop/loopback-next/tree/master/packages/example-getting-started)**: - Tutorial on building a simple application with LoopBack 4 key concepts. + Tutorial on building a simple application with LoopBack 4 key concepts using + bottom-up approach. - **[log-extension](https://github.com/strongloop/loopback-next/tree/master/packages/example-log-extension)**: Tutorial on building a log extension. diff --git a/pages/en/lb4/Testing-the-API.md b/pages/en/lb4/Testing-the-API.md index 62be53eaa..af1ac21d7 100644 --- a/pages/en/lb4/Testing-the-API.md +++ b/pages/en/lb4/Testing-the-API.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues off from [Defining and validating the API](./Defining-and-validating-the-API.html). +This article continues off from [Defining the API using top-down approach](./Defining-the-API-using-top-down-approach.html). " %} {% include important.html content="The top-down approach for building LoopBack diff --git a/users/index.html b/users/index.html index afde72794..7c97d1e0e 100644 --- a/users/index.html +++ b/users/index.html @@ -1,6 +1,7 @@ --- layout: page - title: Who's Using LoopBack item: using + title: Who's Using LoopBack + item: using ---
From 29499ac2c270f5d777c0b050059a980e92ad1c28 Mon Sep 17 00:00:00 2001 From: shimks Date: Wed, 21 Feb 2018 16:37:31 -0500 Subject: [PATCH 2/7] apply feedback --- .../en/lb4/Best-practices-with-Loopback-4.md | 13 +++- ...fining-the-API-using-bottom-up-approach.md | 77 +++++++++++++------ .../en/lb4/Defining-your-testing-strategy.md | 2 +- pages/en/lb4/Implementing-features.md | 2 +- .../lb4/Preparing-the-API-for-consumption.md | 2 +- pages/en/lb4/Testing-the-API.md | 2 +- 6 files changed, 67 insertions(+), 31 deletions(-) diff --git a/pages/en/lb4/Best-practices-with-Loopback-4.md b/pages/en/lb4/Best-practices-with-Loopback-4.md index 76954faf6..0b5b28057 100644 --- a/pages/en/lb4/Best-practices-with-Loopback-4.md +++ b/pages/en/lb4/Best-practices-with-Loopback-4.md @@ -8,14 +8,21 @@ permalink: /doc/en/lb4/Best-practices-with-Loopback-4.html summary: --- +{% include important.html content=" +The top-down approach for building LoopBack +applications is not yet fully supported. Therefore, some of the sections in this +page are outdated and may not work out of the box. They will be revisited after +our MVP release. +" %} + LoopBack 4 is more than just a framework: It’s an ecosystem that encourages developers to follow best practices through predefined standards. This section will walk through some important guidelines by building an example API for a catalog of products. Our best practice follows an "API first" and test-driven development approach: 1. **Defining the API**: There are two possible approaches to take in this section - - [**Defining the API using bottom-up appraoch**](./Defining-the-API-using-bottom-up-approach.html): This section guides you through setting up a skeleton of your application so that a full API can be automatically generated. - - [**Defining the API using top-down approach**](./Defining-the-API-using-top-down-approach.html): This section guides you through constructing your API first before any internal logic is added. - - [**Testing the API**](./Testing-the-API.html): This section describes the process of writing smoke test for your API and its spec. + - [**Defining the API using bottom-up approach**](./Defining-the-API-using-bottom-up-approach.html): This section guides you through setting up a skeleton of your application so that its full OpenAPI specification can be automatically generated. + - [**Defining the API using top-down approach**](./Defining-the-API-using-top-down-approach.html): This section guides you through constructing your API first before any internal logic is added. __*Not fully supported*__ + - [**Testing the API**](./Testing-the-API.html): This section describes the process of writing smoke test for your API and its spec. __*Not fully supported*__ 2. [**Defining your testing strategy**](./Defining-your-testing-strategy.html): This section discusses the advantages and the process of building a strong testing suite. 3. [**Implementing features**](./Implementing-features.html): This section demonstrates how the tests for each feature of your application should be written, and how to write the logic to make these tests pass. In the example, the tests for the controller, model, repository, data source, and sequence are written and then implemented. 4. [**Preparing the API for consumption**](./Preparing-the-API-for-consumption.html): This section shows how the endpoints can be physically tested using the Swagger UI. diff --git a/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md b/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md index ab5177ef0..23dc64911 100644 --- a/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md +++ b/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md @@ -10,16 +10,26 @@ summary: ## Define the API from bottom to top -### Start with LoopBack artfiacts +You may want to build your application from the bottom up if you: + +- do not have a complete understanding of what your existing tools can offer. +- want to capture already existing domain models so that they can be reflected +as APIs for external consumption. +- need to grow and change your API from the initial implementation +- want to set up and run an API from an early stage of the production to +easily envision the big picture of the end product. + +There are various tools available to LoopBack which allows this bottom-up +approach of building your application to be simple through the usages of +metadata and decorators. -Sometimes, it's hard to know what your API is going to look like without -writing out your application first. It also might be difficult to adjust your -API as plans change or as features need to be reworked. +### Start with LoopBack artfiacts With TypeScript's [experimental decorator](https://www.typescriptlang.org/docs/handbook/decorators.html) feature, APIs can be automatically built and exposed as your application continues development. Some key concepts utilize decorators to gather -'metadata' about your code and then assemble them into a valid OpenAPI spec. +_metadata_ about your code and then assemble them into a valid OpenAPI +specification, which provide a description of your API. These concepts and their decorators include: - [Model](Model.html) @@ -31,16 +41,19 @@ These concepts and their decorators include: ### Define your models -Your models will be used to provide schemas to validate against the data -your API will intercept and consequently are likely to be referenced as -argument types in your controllers, so they should be the first to be defined. +Your models act as common definitions between data being handled by the API +layer and the datasource layer. Since your API is going to be built around the +manipulation of models and their properties, they will be the first to be +defined. {% include note.html content=" `Todo` model from [tutorial](TUTORIAL LINK) is used for demonstration here. " %} First, write a simple TypeScript class describing your model and its -properties. +properties: + +{% include code-caption.html content="src/models/todo.model.ts" %} ```ts export class Todo { @@ -51,11 +64,21 @@ export class Todo { } ``` -This model is just a TypeScript class without any decorators in its current -form, so features such as automatic schema generation are not available to it -yet. +To this representation of your model, we can use the `@model` and `@property` +decorators to create the model's _metadata_; a model definition. +LoopBack and LoopBack extensions can use this model definition for +a wide variety of uses, such as: + +- generating OpenAPI schema for your APIs +- validating instances of the models during the request/response lifecycle +- automatically inferring relationships between models during datasource +operations -Now decorate the class with `@model` and `@property`. +To apply these decorators to your model, you simply prefix the class definition +with the `@model` decorator, and prefix each property with the +`@property` decorator: + +{% include code-caption.html content="src/models/todo.model.ts" %} ```ts import {model, property} from '@loopback/repository'; @@ -72,10 +95,6 @@ export class Todo { } ``` -Once the model has been decorated with these decorators, -its metadata is made available to the app and the model is ready to have its -corresponding OpenAPI schema generated. - ### Define your routes {% include note.html content=" @@ -84,10 +103,14 @@ corresponding OpenAPI schema generated. " %} Once your models are defined, create a controller to host your routes -for each categories of your API. +for each [paths](https://swagger.io/specification/#pathsObject) of your API: + +{% include code-caption.html content="src/controllers/todo.controller.ts" %} ```ts -class TodoController { +import {Todo} from '../models/todo.model'; + +export class TodoController { constructor() {} async createTodo(todo: Todo) { @@ -103,14 +126,19 @@ class TodoController { ``` The controller's routes in their current state has no information on which -API endpoints they belong to. Add them in by using `@operation` and `@param` -decorators. +API endpoints they belong to. Add them in by appending `@operation` to each +method of your routes and `@param` to its parameters: + +{% include code-caption.html content="src/controllers/todo.controller.ts" %} ```ts -class TodoController { +import {Todo} from '../models/todo.model'; +import {post, get, param} from '@loopback/openapi-v2'; + +export class TodoController { constructor() {} - @post('/todo') // sugar for @operation('post', '/todo'); + @post('/todo') // same as @operation('post', '/todo'); async createTodo(@param.body('todo') todo: Todo) { // data creating logic goes here } @@ -128,7 +156,7 @@ class TodoController { ``` Once your routes have been decorated, your application is ready to serve -its API; when an instance of `RestServer` is run, an OpenAPI specification +its API. When an instance of `RestServer` is run, an OpenAPI specification representing your application's API is built. The spec is generated entirely from the decorated elements' metadata, which in turn provides routing logic for your API when your application is running. @@ -137,6 +165,7 @@ routing logic for your API when your application is running. To review your complete API specification, run your application with the decorated controllers registered. Once it is running, visit `/swagger.json` +to access your spec in JSON format or `/swagger.yaml` for YAML. endpoint to see your API specification. Alternatively, the specification file can also be accessed in code through the `getApiSpec()` function from your `RestServer` instance. diff --git a/pages/en/lb4/Defining-your-testing-strategy.md b/pages/en/lb4/Defining-your-testing-strategy.md index 98d232ec7..de32e5fbc 100644 --- a/pages/en/lb4/Defining-your-testing-strategy.md +++ b/pages/en/lb4/Defining-your-testing-strategy.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues off from [Testing the API](./Testing-the-API.html) and [Defining the API using bottom-up approach](./Defining-the-API-using-bottom-up-approach.html). +This article continues from [Testing the API](./Testing-the-API.html) and [Defining the API using bottom-up approach](./Defining-the-API-using-bottom-up-approach.html). " %} ## Define your testing strategy diff --git a/pages/en/lb4/Implementing-features.md b/pages/en/lb4/Implementing-features.md index f30ddf230..f13bbc701 100644 --- a/pages/en/lb4/Implementing-features.md +++ b/pages/en/lb4/Implementing-features.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues off from [Defining your testing stategy](./Defining-your-testing-strategy.html). +This article continues from [Defining your testing stategy](./Defining-your-testing-strategy.html). " %} ## Incrementally implement features diff --git a/pages/en/lb4/Preparing-the-API-for-consumption.md b/pages/en/lb4/Preparing-the-API-for-consumption.md index 891f7e735..d8c842f01 100644 --- a/pages/en/lb4/Preparing-the-API-for-consumption.md +++ b/pages/en/lb4/Preparing-the-API-for-consumption.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues off from [Implementing features](./Implementing-features.html). +This article continues from [Implementing features](./Implementing-features.html). " %} ## Preparing your API for consumption diff --git a/pages/en/lb4/Testing-the-API.md b/pages/en/lb4/Testing-the-API.md index af1ac21d7..754371d24 100644 --- a/pages/en/lb4/Testing-the-API.md +++ b/pages/en/lb4/Testing-the-API.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues off from [Defining the API using top-down approach](./Defining-the-API-using-top-down-approach.html). +This article continues from [Defining the API using top-down approach](./Defining-the-API-using-top-down-approach.html). " %} {% include important.html content="The top-down approach for building LoopBack From adae173cf942cff0173485e519c62371182fbd46 Mon Sep 17 00:00:00 2001 From: shimks Date: Wed, 21 Feb 2018 16:59:27 -0500 Subject: [PATCH 3/7] add tutorial links --- .../Defining-the-API-using-bottom-up-approach.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md b/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md index 23dc64911..96062b24f 100644 --- a/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md +++ b/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md @@ -47,7 +47,8 @@ manipulation of models and their properties, they will be the first to be defined. {% include note.html content=" - `Todo` model from [tutorial](TUTORIAL LINK) is used for demonstration here. + `Todo` model from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/4-todo-model.md#srcmodelstodomodelts) + is used for demonstration here. " %} First, write a simple TypeScript class describing your model and its @@ -98,7 +99,8 @@ export class Todo { ### Define your routes {% include note.html content=" - `TodoController` from [tutorial](TUTORIAL LINK) is used for + `TodoController` from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/7-controller.md#srccontrollerstodocontrollerts) + is used for demonstration here. " %} @@ -165,13 +167,12 @@ routing logic for your API when your application is running. To review your complete API specification, run your application with the decorated controllers registered. Once it is running, visit `/swagger.json` -to access your spec in JSON format or `/swagger.yaml` for YAML. -endpoint to see your API specification. Alternatively, the specification file -can also be accessed in code through the `getApiSpec()` function from your -`RestServer` instance. +endpoint to access your API specification in JSON format or `/swagger.yaml` +for YAML. Alternatively, the specification file can also be accessed +in code through the `getApiSpec()` function from your `RestServer` instance. For a complete walkthrough of developing an application with the bottom-up -approach, see our [Todo application](LINK TO TUTORIAL) +approach, see our [Todo application](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/README.md#loopbackexample-getting-started) tutorial. {% include note.html content=" From 5fae1c4ce8dcc21cfdcfa013501df5b11c40a918 Mon Sep 17 00:00:00 2001 From: shimks Date: Fri, 23 Feb 2018 14:41:23 -0500 Subject: [PATCH 4/7] change titles of bottom-up top-down --- _data/sidebars/lb4_sidebar.yml | 8 ++++---- pages/en/lb4/Best-practices-with-Loopback-4.md | 6 +++--- ...md => Defining-the-API-using-API-first-approach.md} | 8 ++++---- ...d => Defining-the-API-using-code-first-approach.md} | 10 +++++----- pages/en/lb4/Defining-your-testing-strategy.md | 2 +- pages/en/lb4/Testing-the-API.md | 2 +- 6 files changed, 18 insertions(+), 18 deletions(-) rename pages/en/lb4/{Defining-the-API-using-top-down-approach.md => Defining-the-API-using-API-first-approach.md} (97%) rename pages/en/lb4/{Defining-the-API-using-bottom-up-approach.md => Defining-the-API-using-code-first-approach.md} (94%) diff --git a/_data/sidebars/lb4_sidebar.yml b/_data/sidebars/lb4_sidebar.yml index 21cd85351..aadf19e75 100644 --- a/_data/sidebars/lb4_sidebar.yml +++ b/_data/sidebars/lb4_sidebar.yml @@ -111,12 +111,12 @@ children: output: 'web, pdf' children: - - title: 'Defining the API using bottom-up approach' - url: Defining-the-API-using-bottom-up-approach.html + - title: 'Defining the API using code-first approach' + url: Defining-the-API-using-code-first-approach.html output: 'web, pdf' - - title: 'Defining the API using top-down approach' - url: Defining-the-API-using-top-down-approach.html + - title: 'Defining the API using API-first approach' + url: Defining-the-API-using-API-first-approach.html output: 'web, pdf' children: diff --git a/pages/en/lb4/Best-practices-with-Loopback-4.md b/pages/en/lb4/Best-practices-with-Loopback-4.md index 0b5b28057..4c6a9eb02 100644 --- a/pages/en/lb4/Best-practices-with-Loopback-4.md +++ b/pages/en/lb4/Best-practices-with-Loopback-4.md @@ -9,7 +9,7 @@ summary: --- {% include important.html content=" -The top-down approach for building LoopBack +The API-first approach for building LoopBack applications is not yet fully supported. Therefore, some of the sections in this page are outdated and may not work out of the box. They will be revisited after our MVP release. @@ -20,8 +20,8 @@ LoopBack 4 is more than just a framework: It’s an ecosystem that encourages de Our best practice follows an "API first" and test-driven development approach: 1. **Defining the API**: There are two possible approaches to take in this section - - [**Defining the API using bottom-up approach**](./Defining-the-API-using-bottom-up-approach.html): This section guides you through setting up a skeleton of your application so that its full OpenAPI specification can be automatically generated. - - [**Defining the API using top-down approach**](./Defining-the-API-using-top-down-approach.html): This section guides you through constructing your API first before any internal logic is added. __*Not fully supported*__ + - [**Defining the API using code-first approach**](./Defining-the-API-using-code-first-approach.html): This section guides you through setting up a skeleton of your application so that its full OpenAPI specification can be automatically generated. + - [**Defining the API using API-first approach**](./Defining-the-API-using-API-first-approach.html): This section guides you through constructing your API first before any internal logic is added. __*Not fully supported*__ - [**Testing the API**](./Testing-the-API.html): This section describes the process of writing smoke test for your API and its spec. __*Not fully supported*__ 2. [**Defining your testing strategy**](./Defining-your-testing-strategy.html): This section discusses the advantages and the process of building a strong testing suite. 3. [**Implementing features**](./Implementing-features.html): This section demonstrates how the tests for each feature of your application should be written, and how to write the logic to make these tests pass. In the example, the tests for the controller, model, repository, data source, and sequence are written and then implemented. diff --git a/pages/en/lb4/Defining-the-API-using-top-down-approach.md b/pages/en/lb4/Defining-the-API-using-API-first-approach.md similarity index 97% rename from pages/en/lb4/Defining-the-API-using-top-down-approach.md rename to pages/en/lb4/Defining-the-API-using-API-first-approach.md index 7d0e654d1..c60fdda4b 100644 --- a/pages/en/lb4/Defining-the-API-using-top-down-approach.md +++ b/pages/en/lb4/Defining-the-API-using-API-first-approach.md @@ -1,10 +1,10 @@ --- lang: en -title: 'Defining the API using top-down approach' +title: 'Defining the API using API-first approach' keywords: LoopBack 4.0, LoopBack 4 tags: sidebar: lb4_sidebar -permalink: /doc/en/lb4/Defining-the-API-using-top-down-approach.html +permalink: /doc/en/lb4/Defining-the-API-using-API-first-approach.html summary: --- {% include important.html content="The top-down approach for building LoopBack @@ -13,7 +13,7 @@ page are outdated and may not work out of the box. They will be revisited after our MVP release. "%} -## Define the API from top to bottom +## Define the API from top to bottom (API-first) ### Start with data @@ -354,7 +354,7 @@ See [Validate your OpenAPI specification](Testing-your-application.html#validate {% include note.html content=" If you would like to make tweaks to your API as you develop your application, - refer to [Defining the API using bottom-up approach](Defining-the-API-using-bottom-up-approach) + refer to [Defining the API using code-first approach](Defining-the-API-using-code-first-approach) page for best practices. " %} diff --git a/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md b/pages/en/lb4/Defining-the-API-using-code-first-approach.md similarity index 94% rename from pages/en/lb4/Defining-the-API-using-bottom-up-approach.md rename to pages/en/lb4/Defining-the-API-using-code-first-approach.md index 96062b24f..e68a14843 100644 --- a/pages/en/lb4/Defining-the-API-using-bottom-up-approach.md +++ b/pages/en/lb4/Defining-the-API-using-code-first-approach.md @@ -1,16 +1,16 @@ --- lang: en -title: 'Defining the API using bottom up approach' +title: 'Defining the API using code-first approach' keywords: LoopBack 4.0, LoopBack 4 tags: sidebar: lb4_sidebar -permalink: /doc/en/lb4/Defining-the-API-using-bottom-up-approach.html +permalink: /doc/en/lb4/Defining-the-API-using-code-first-approach.html summary: --- -## Define the API from bottom to top +## Define the API from code-first approach -You may want to build your application from the bottom up if you: +You may want to build your application from the 'bottom up' if you: - do not have a complete understanding of what your existing tools can offer. - want to capture already existing domain models so that they can be reflected @@ -177,7 +177,7 @@ tutorial. {% include note.html content=" If you would like to create your API manually or already have one designed, - refer to [Defining the API using top-down approach](Defining-the-API-using-top-down-approach) + refer to [Defining the API using API-first approach](Defining-the-API-using-API-first-approach) page for best practices. " %} diff --git a/pages/en/lb4/Defining-your-testing-strategy.md b/pages/en/lb4/Defining-your-testing-strategy.md index de32e5fbc..efe370595 100644 --- a/pages/en/lb4/Defining-your-testing-strategy.md +++ b/pages/en/lb4/Defining-your-testing-strategy.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues from [Testing the API](./Testing-the-API.html) and [Defining the API using bottom-up approach](./Defining-the-API-using-bottom-up-approach.html). +This article continues from [Testing the API](./Testing-the-API.html) and [Defining the API using code-first approach](./Defining-the-API-using-code-first-approach.html). " %} ## Define your testing strategy diff --git a/pages/en/lb4/Testing-the-API.md b/pages/en/lb4/Testing-the-API.md index 754371d24..90085863f 100644 --- a/pages/en/lb4/Testing-the-API.md +++ b/pages/en/lb4/Testing-the-API.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues from [Defining the API using top-down approach](./Defining-the-API-using-top-down-approach.html). +This article continues from [Defining the API using API-first approach](./Defining-the-API-using-API-first-approach.html). " %} {% include important.html content="The top-down approach for building LoopBack From c37259cc66db0234fc50d3e06f8587f051a19c55 Mon Sep 17 00:00:00 2001 From: shimks Date: Mon, 5 Mar 2018 11:27:59 -0500 Subject: [PATCH 5/7] change defining-the-api to -app --- _data/sidebars/lb4_sidebar.yml | 4 ++-- pages/en/lb4/Best-practices-with-Loopback-4.md | 2 +- pages/en/lb4/Defining-the-API-using-code-first-approach.md | 2 +- ...oach.md => Defining-the-app-using-API-first-approach.md} | 6 +++--- pages/en/lb4/Testing-the-API.md | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) rename pages/en/lb4/{Defining-the-API-using-API-first-approach.md => Defining-the-app-using-API-first-approach.md} (98%) diff --git a/_data/sidebars/lb4_sidebar.yml b/_data/sidebars/lb4_sidebar.yml index aadf19e75..de8f3b9a4 100644 --- a/_data/sidebars/lb4_sidebar.yml +++ b/_data/sidebars/lb4_sidebar.yml @@ -115,8 +115,8 @@ children: url: Defining-the-API-using-code-first-approach.html output: 'web, pdf' - - title: 'Defining the API using API-first approach' - url: Defining-the-API-using-API-first-approach.html + - title: 'Defining the app using API-first approach' + url: Defining-the-app-using-API-first-approach.html output: 'web, pdf' children: diff --git a/pages/en/lb4/Best-practices-with-Loopback-4.md b/pages/en/lb4/Best-practices-with-Loopback-4.md index 4c6a9eb02..472967aff 100644 --- a/pages/en/lb4/Best-practices-with-Loopback-4.md +++ b/pages/en/lb4/Best-practices-with-Loopback-4.md @@ -21,7 +21,7 @@ Our best practice follows an "API first" and test-driven development approach: 1. **Defining the API**: There are two possible approaches to take in this section - [**Defining the API using code-first approach**](./Defining-the-API-using-code-first-approach.html): This section guides you through setting up a skeleton of your application so that its full OpenAPI specification can be automatically generated. - - [**Defining the API using API-first approach**](./Defining-the-API-using-API-first-approach.html): This section guides you through constructing your API first before any internal logic is added. __*Not fully supported*__ + - [**Defining the app using API-first approach**](./Defining-the-app-using-API-first-approach.html): This section guides you through constructing your API first before any internal logic is added. __*Not fully supported*__ - [**Testing the API**](./Testing-the-API.html): This section describes the process of writing smoke test for your API and its spec. __*Not fully supported*__ 2. [**Defining your testing strategy**](./Defining-your-testing-strategy.html): This section discusses the advantages and the process of building a strong testing suite. 3. [**Implementing features**](./Implementing-features.html): This section demonstrates how the tests for each feature of your application should be written, and how to write the logic to make these tests pass. In the example, the tests for the controller, model, repository, data source, and sequence are written and then implemented. diff --git a/pages/en/lb4/Defining-the-API-using-code-first-approach.md b/pages/en/lb4/Defining-the-API-using-code-first-approach.md index e68a14843..c75788bcd 100644 --- a/pages/en/lb4/Defining-the-API-using-code-first-approach.md +++ b/pages/en/lb4/Defining-the-API-using-code-first-approach.md @@ -177,7 +177,7 @@ tutorial. {% include note.html content=" If you would like to create your API manually or already have one designed, - refer to [Defining the API using API-first approach](Defining-the-API-using-API-first-approach) + refer to [Defining the app using API-first approach](Defining-the-app-using-API-first-approach) page for best practices. " %} diff --git a/pages/en/lb4/Defining-the-API-using-API-first-approach.md b/pages/en/lb4/Defining-the-app-using-API-first-approach.md similarity index 98% rename from pages/en/lb4/Defining-the-API-using-API-first-approach.md rename to pages/en/lb4/Defining-the-app-using-API-first-approach.md index c60fdda4b..08ddf09a4 100644 --- a/pages/en/lb4/Defining-the-API-using-API-first-approach.md +++ b/pages/en/lb4/Defining-the-app-using-API-first-approach.md @@ -1,10 +1,10 @@ --- lang: en -title: 'Defining the API using API-first approach' +title: 'Defining the app using API-first approach' keywords: LoopBack 4.0, LoopBack 4 tags: sidebar: lb4_sidebar -permalink: /doc/en/lb4/Defining-the-API-using-API-first-approach.html +permalink: /doc/en/lb4/Defining-the-app-using-API-first-approach.html summary: --- {% include important.html content="The top-down approach for building LoopBack @@ -13,7 +13,7 @@ page are outdated and may not work out of the box. They will be revisited after our MVP release. "%} -## Define the API from top to bottom (API-first) +## Define the app from top to bottom (API-first) ### Start with data diff --git a/pages/en/lb4/Testing-the-API.md b/pages/en/lb4/Testing-the-API.md index 90085863f..ebef59393 100644 --- a/pages/en/lb4/Testing-the-API.md +++ b/pages/en/lb4/Testing-the-API.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues from [Defining the API using API-first approach](./Defining-the-API-using-API-first-approach.html). +This article continues from [Defining the app using API-first approach](./Defining-the-app-using-API-first-approach.html). " %} {% include important.html content="The top-down approach for building LoopBack From 6f38886475e1f7bc6dc78258896309e4947e07aa Mon Sep 17 00:00:00 2001 From: shimks Date: Mon, 5 Mar 2018 14:44:22 -0500 Subject: [PATCH 6/7] change to design-first --- _data/sidebars/lb4_sidebar.yml | 4 ++-- pages/en/lb4/Best-practices-with-Loopback-4.md | 2 +- pages/en/lb4/Defining-the-API-using-code-first-approach.md | 6 +++--- ...h.md => Defining-the-API-using-design-first-approach.md} | 6 +++--- pages/en/lb4/Testing-the-API.md | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) rename pages/en/lb4/{Defining-the-app-using-API-first-approach.md => Defining-the-API-using-design-first-approach.md} (98%) diff --git a/_data/sidebars/lb4_sidebar.yml b/_data/sidebars/lb4_sidebar.yml index de8f3b9a4..a357da771 100644 --- a/_data/sidebars/lb4_sidebar.yml +++ b/_data/sidebars/lb4_sidebar.yml @@ -115,8 +115,8 @@ children: url: Defining-the-API-using-code-first-approach.html output: 'web, pdf' - - title: 'Defining the app using API-first approach' - url: Defining-the-app-using-API-first-approach.html + - title: 'Defining the API using design-first approach' + url: Defining-the-API-using-design-first-approach.html output: 'web, pdf' children: diff --git a/pages/en/lb4/Best-practices-with-Loopback-4.md b/pages/en/lb4/Best-practices-with-Loopback-4.md index 472967aff..c9a6bc072 100644 --- a/pages/en/lb4/Best-practices-with-Loopback-4.md +++ b/pages/en/lb4/Best-practices-with-Loopback-4.md @@ -21,7 +21,7 @@ Our best practice follows an "API first" and test-driven development approach: 1. **Defining the API**: There are two possible approaches to take in this section - [**Defining the API using code-first approach**](./Defining-the-API-using-code-first-approach.html): This section guides you through setting up a skeleton of your application so that its full OpenAPI specification can be automatically generated. - - [**Defining the app using API-first approach**](./Defining-the-app-using-API-first-approach.html): This section guides you through constructing your API first before any internal logic is added. __*Not fully supported*__ + - [**Defining the API using design-first approach**](./Defining-the-API-using-design-first-approach.html): This section guides you through constructing your API first before any internal logic is added. __*Not fully supported*__ - [**Testing the API**](./Testing-the-API.html): This section describes the process of writing smoke test for your API and its spec. __*Not fully supported*__ 2. [**Defining your testing strategy**](./Defining-your-testing-strategy.html): This section discusses the advantages and the process of building a strong testing suite. 3. [**Implementing features**](./Implementing-features.html): This section demonstrates how the tests for each feature of your application should be written, and how to write the logic to make these tests pass. In the example, the tests for the controller, model, repository, data source, and sequence are written and then implemented. diff --git a/pages/en/lb4/Defining-the-API-using-code-first-approach.md b/pages/en/lb4/Defining-the-API-using-code-first-approach.md index c75788bcd..5a978f23e 100644 --- a/pages/en/lb4/Defining-the-API-using-code-first-approach.md +++ b/pages/en/lb4/Defining-the-API-using-code-first-approach.md @@ -47,7 +47,7 @@ manipulation of models and their properties, they will be the first to be defined. {% include note.html content=" - `Todo` model from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/4-todo-model.md#srcmodelstodomodelts) + `Todo` model from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/model.md#srcmodelstodomodelts) is used for demonstration here. " %} @@ -99,7 +99,7 @@ export class Todo { ### Define your routes {% include note.html content=" - `TodoController` from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/7-controller.md#srccontrollerstodocontrollerts) + `TodoController` from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/controller.md#srccontrollerstodocontrollerts-2) is used for demonstration here. " %} @@ -177,7 +177,7 @@ tutorial. {% include note.html content=" If you would like to create your API manually or already have one designed, - refer to [Defining the app using API-first approach](Defining-the-app-using-API-first-approach) + refer to [Defining the API using design-first approach](Defining-the-API-using-design-first-approach) page for best practices. " %} diff --git a/pages/en/lb4/Defining-the-app-using-API-first-approach.md b/pages/en/lb4/Defining-the-API-using-design-first-approach.md similarity index 98% rename from pages/en/lb4/Defining-the-app-using-API-first-approach.md rename to pages/en/lb4/Defining-the-API-using-design-first-approach.md index 08ddf09a4..9aedfd2e8 100644 --- a/pages/en/lb4/Defining-the-app-using-API-first-approach.md +++ b/pages/en/lb4/Defining-the-API-using-design-first-approach.md @@ -1,10 +1,10 @@ --- lang: en -title: 'Defining the app using API-first approach' +title: 'Defining the API using design-first approach' keywords: LoopBack 4.0, LoopBack 4 tags: sidebar: lb4_sidebar -permalink: /doc/en/lb4/Defining-the-app-using-API-first-approach.html +permalink: /doc/en/lb4/Defining-the-API-using-design-first-approach.html summary: --- {% include important.html content="The top-down approach for building LoopBack @@ -13,7 +13,7 @@ page are outdated and may not work out of the box. They will be revisited after our MVP release. "%} -## Define the app from top to bottom (API-first) +## Define the API from top to bottom (design-first) ### Start with data diff --git a/pages/en/lb4/Testing-the-API.md b/pages/en/lb4/Testing-the-API.md index ebef59393..4978f3fa5 100644 --- a/pages/en/lb4/Testing-the-API.md +++ b/pages/en/lb4/Testing-the-API.md @@ -9,7 +9,7 @@ summary: --- {% include previous.html content=" -This article continues from [Defining the app using API-first approach](./Defining-the-app-using-API-first-approach.html). +This article continues from [Defining the API using design-first approach](./Defining-the-API-using-design-first-approach.html). " %} {% include important.html content="The top-down approach for building LoopBack From 2e52996a83942cecb467e768f3a8b201d2ff742c Mon Sep 17 00:00:00 2001 From: shimks Date: Fri, 9 Mar 2018 12:55:26 -0500 Subject: [PATCH 7/7] switch to openapi-v3 --- ...ining-the-API-using-code-first-approach.md | 62 +++++++++---------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/pages/en/lb4/Defining-the-API-using-code-first-approach.md b/pages/en/lb4/Defining-the-API-using-code-first-approach.md index 5a978f23e..cf97d48ae 100644 --- a/pages/en/lb4/Defining-the-API-using-code-first-approach.md +++ b/pages/en/lb4/Defining-the-API-using-code-first-approach.md @@ -12,12 +12,12 @@ summary: You may want to build your application from the 'bottom up' if you: -- do not have a complete understanding of what your existing tools can offer. -- want to capture already existing domain models so that they can be reflected -as APIs for external consumption. -- need to grow and change your API from the initial implementation -- want to set up and run an API from an early stage of the production to -easily envision the big picture of the end product. +* do not have a complete understanding of what your existing tools can offer. +* want to capture already existing domain models so that they can be reflected + as APIs for external consumption. +* need to grow and change your API from the initial implementation +* want to set up and run an API from an early stage of the production to + easily envision the big picture of the end product. There are various tools available to LoopBack which allows this bottom-up approach of building your application to be simple through the usages of @@ -32,12 +32,12 @@ _metadata_ about your code and then assemble them into a valid OpenAPI specification, which provide a description of your API. These concepts and their decorators include: -- [Model](Model.html) - - `@model()` - - `@property()` -- [Routes](Routes.html) - - `@operation()` - - `@param()` +* [Model](Model.html) + * `@model()` + * `@property()` +* [Routes](Routes.html) + * `@operation()` + * `@param()` ### Define your models @@ -47,8 +47,8 @@ manipulation of models and their properties, they will be the first to be defined. {% include note.html content=" - `Todo` model from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/model.md#srcmodelstodomodelts) - is used for demonstration here. +`Todo` model from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/model.md#srcmodelstodomodelts) +is used for demonstration here. " %} First, write a simple TypeScript class describing your model and its @@ -70,10 +70,10 @@ decorators to create the model's _metadata_; a model definition. LoopBack and LoopBack extensions can use this model definition for a wide variety of uses, such as: -- generating OpenAPI schema for your APIs -- validating instances of the models during the request/response lifecycle -- automatically inferring relationships between models during datasource -operations +* generating OpenAPI schema for your APIs +* validating instances of the models during the request/response lifecycle +* automatically inferring relationships between models during datasource + operations To apply these decorators to your model, you simply prefix the class definition with the `@model` decorator, and prefix each property with the @@ -88,7 +88,7 @@ import {model, property} from '@loopback/repository'; export class Todo { @property() id?: number; @property({ - required: true + required: true, }) title: string; @property() desc?: string; @@ -99,9 +99,9 @@ export class Todo { ### Define your routes {% include note.html content=" - `TodoController` from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/controller.md#srccontrollerstodocontrollerts-2) - is used for - demonstration here. +`TodoController` from [tutorial](https://github.com/strongloop/loopback-next/blob/master/packages/example-getting-started/docs/controller.md#srccontrollerstodocontrollerts-2) +is used for +demonstration here. " %} Once your models are defined, create a controller to host your routes @@ -129,26 +129,26 @@ export class TodoController { The controller's routes in their current state has no information on which API endpoints they belong to. Add them in by appending `@operation` to each -method of your routes and `@param` to its parameters: +method of your routes and `@param` or `@requestBody` to its parameters: {% include code-caption.html content="src/controllers/todo.controller.ts" %} ```ts import {Todo} from '../models/todo.model'; -import {post, get, param} from '@loopback/openapi-v2'; +import {post, get, param, requestBody} from '@loopback/openapi-v3'; export class TodoController { constructor() {} @post('/todo') // same as @operation('post', '/todo'); - async createTodo(@param.body('todo') todo: Todo) { + async createTodo(@requestBody() todo: Todo) { // data creating logic goes here } @get('/todo/{id}') async findTodoById( @param.path.number('id') id: number, - @param.query.boolean('items') items?: boolean + @param.query.boolean('items') items?: boolean, ): Promise { // data retrieving logic goes here } @@ -166,8 +166,8 @@ routing logic for your API when your application is running. ### Reviewing your API specification To review your complete API specification, run your application with the -decorated controllers registered. Once it is running, visit `/swagger.json` -endpoint to access your API specification in JSON format or `/swagger.yaml` +decorated controllers registered. Once it is running, visit `/openapi.json` +endpoint to access your API specification in JSON format or `/openapi.yaml` for YAML. Alternatively, the specification file can also be accessed in code through the `getApiSpec()` function from your `RestServer` instance. @@ -176,9 +176,9 @@ approach, see our [Todo application](https://github.com/strongloop/loopback-next tutorial. {% include note.html content=" - If you would like to create your API manually or already have one designed, - refer to [Defining the API using design-first approach](Defining-the-API-using-design-first-approach) - page for best practices. +If you would like to create your API manually or already have one designed, +refer to [Defining the API using design-first approach](Defining-the-API-using-design-first-approach) +page for best practices. " %} {% include next.html content= "