Skip to content

Commit a58b8d3

Browse files
authored
docs(guides): General proofread of the basics docs (#2983)
1 parent cb56c73 commit a58b8d3

8 files changed

Lines changed: 116 additions & 61 deletions

File tree

.github/contributing.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Before running the tests from the `test/` folder `npm test` will run ESlint. You
4040

4141
### Documentation
4242

43-
Feathers documentation is contained in Markdown files in the [docs folder](https://github.com/feathersjs/feathers) of the mainr repository. To change the documentation submit a pull request to that repo, referencing any other PR if applicable, and the docs will be updated as soon as it is merged.
43+
Feathers documentation is contained in Markdown files in the [docs folder](https://github.com/feathersjs/feathers) of the main repository. To change the documentation submit a pull request to that repo, referencing any other PR if applicable, and the docs will be updated as soon as it is merged.
4444

4545
## Community Contributions
4646

docs/guides/basics/authentication.md

Lines changed: 49 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ outline: deep
44

55
# Authentication
66

7-
We now have a fully functional chat application consisting of [services](./services.md) and [schemas](./schemas.md). The services come with authentication enabled by default, so before we can use it we need to create a new user and learn how Feathers authentication works. We will look at authenticating our REST API, and then how to authenticate with Feathers in the browser. Finally we will implement a "Login with GitHub".
7+
We now have a fully functional chat application consisting of [services](./services.md) and [schemas](./schemas.md). The services come with authentication enabled by default, so before we can use it we need to create a new user and learn how Feathers authentication works. We will look at authenticating our REST API, and then how to authenticate with Feathers in the browser. Finally we will implement a "Login with GitHub" button.
88

99
## Registering a user
1010

@@ -36,33 +36,49 @@ For SQL databases, creating a user with the same email address will only work on
3636

3737
This will return something like this:
3838

39+
<DatabaseBlock global-id="sql">
40+
3941
```json
4042
{
41-
"id": "<user id>",
43+
"id": 123,
4244
"email": "[email protected]",
4345
"avatar": "https://s.gravatar.com/avatar/ffe2a09df37d7c646e974a2d2b8d3e03?s=60"
4446
}
4547
```
4648

49+
</DatabaseBlock>
50+
51+
<DatabaseBlock global-id="mongodb">
52+
53+
```json
54+
{
55+
"_id": "63c00098502debdeec31bd77",
56+
"email": "[email protected]",
57+
"avatar": "https://s.gravatar.com/avatar/ffe2a09df37d7c646e974a2d2b8d3e03?s=60"
58+
}
59+
```
60+
61+
</DatabaseBlock>
62+
4763
Which means our user has been created successfully.
4864

4965
<BlockQuote type="info">
5066

51-
The password is stored securely in the database but will never be included in an external response.
67+
The password has been encrypted and stored securely in the database but will never be included in an external response.
5268

5369
</BlockQuote>
5470

5571
## Logging in
5672

57-
By default, Feathers uses [JSON web token](https://jwt.io/) for authentication. It is an access token that is valid for a limited time (one day by default) that is issued by the Feathers server and needs to be sent with every API request that requires authentication. Usually a token is issued for a specific user and in our case we want a JWT for the user we just created.
73+
By default, Feathers uses [JSON Web Tokens](https://jwt.io/) for authentication. It is an access token that is issued by the Feathers server for a limited time (one day by default) and needs to be sent with every API request that requires authentication. Usually a token is issued for a specific user, Let's see if we can issue a JWT for the user that we just created.
5874

5975
<BlockQuote type="tip">
6076

6177
If you are wondering why Feathers is using JWT for authentication, have a look at [this FAQ](../../help/faq.md#why-are-you-using-jwt-for-sessions).
6278

6379
</BlockQuote>
6480

65-
Tokens can be created by sending a POST request to the `/authentication` endpoint (which is the same as calling the `create` method on the `authentication` service set up in `src/authentication`) and passing the authentication strategy you want to use. To get a token for an existing user through a username (email) and password login we can use the built-in `local` authentication strategy with a request like this:
81+
Tokens can be created by sending a POST request to the `/authentication` endpoint (which is the same as calling the `create` method on the `authentication` service set up in `src/authentication`) and passing the authentication strategy you want to use along with any other relevant data. To get a token for an existing user through a username (email) and password login, we can use the built-in `local` authentication strategy with a request like this:
6682

6783
```js
6884
// POST /authentication
@@ -85,20 +101,42 @@ curl 'http://localhost:3030/authentication/' \
85101

86102
This will return something like this:
87103

104+
<DatabaseBlock global-id="sql">
105+
88106
```json
89107
{
90108
"accessToken": "<JWT for this user>",
91109
"authentication": {
92110
"strategy": "local"
93111
},
94112
"user": {
95-
"id": "<user id>",
113+
"id": 123,
96114
"email": "[email protected]",
97115
"avatar": "https://s.gravatar.com/avatar/ffe2a09df37d7c646e974a2d2b8d3e03?s=60"
98116
}
99117
}
100118
```
101119

120+
</DatabaseBlock>
121+
122+
<DatabaseBlock global-id="mongodb">
123+
124+
```json
125+
{
126+
"accessToken": "<JWT for this user>",
127+
"authentication": {
128+
"strategy": "local"
129+
},
130+
"user": {
131+
"_id": "63c00098502debdeec31bd77",
132+
"email": "[email protected]",
133+
"avatar": "https://s.gravatar.com/avatar/ffe2a09df37d7c646e974a2d2b8d3e03?s=60"
134+
}
135+
}
136+
```
137+
138+
</DatabaseBlock>
139+
102140
The `accessToken` can now be used for other REST requests that require authentication by sending the `Authorization: Bearer <accessToken>` HTTP header. For example to create a new message:
103141

104142
```sh
@@ -114,11 +152,13 @@ Make sure to replace the `<accessToken>` in the above request. For more informat
114152

115153
</BlockQuote>
116154

155+
That's pretty neat, but emails and passwords are boring, let's spice things up a bit.
156+
117157
## Login with GitHub
118158

119-
OAuth is an open authentication standard supported by almost every major platform and what gets us the log in with Facebook, Google, GitHub etc. buttons. From the Feathers perspective the authentication flow is pretty similar. Instead of authenticating with the `local` strategy by sending a username and password, Feathers directs the user to authorize the application with the login provider. If it is successful Feathers authentication finds or creates the user in the `users` service with the information it got back from the provider and then issues a token for them.
159+
OAuth is an open authentication standard supported by almost every major social platform and what gets us the log in with Facebook, Google, GitHub etc. buttons. From the Feathers perspective, the authentication flow with OAuth is pretty similar. Instead of authenticating with the `local` strategy by sending a username and password, Feathers directs the user to authorize the application with the login provider. If it is successful, Feathers authentication finds or creates the user in the `users` service with the information it got back from the provider and then issues a token for them.
120160

121-
To allow login with GitHub, first, we have to [create a new OAuth application on GitHub](https://github.com/settings/applications/new). You can put anything in the name, homepage and description fields. The callback URL **must** be set to
161+
To allow login with GitHub, we first have to [create a new OAuth application on GitHub](https://github.com/settings/applications/new). You can put anything in the name, homepage and description fields. The callback URL **must** be set to
122162

123163
```sh
124164
http://localhost:3030/oauth/github/callback
@@ -132,7 +172,7 @@ You can find your existing applications in the [GitHub OAuth apps developer sett
132172

133173
</BlockQuote>
134174

135-
Once you clicked "Register application" we have to update our Feathers app configuration with the client id and secret copied from the GitHub application settings:
175+
Once you've clicked "Register application", we need to update our Feathers app configuration with the client id and secret copied from the GitHub application settings:
136176

137177
![Screenshot of the created GitHub application client id and secret](./assets/github-keys.png)
138178

docs/guides/basics/generator.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ You can create a new Feathers application by running `npm create feathers <name>
1818
npm create feathers@pre feathers-chat
1919
```
2020

21-
If you never ran the command before you might be ask to confirm the package installation by pressing enter.
21+
If you never ran the command before you might be asked to confirm the package installation by pressing enter.
2222

2323
<BlockQuote type="warning">
2424

@@ -137,4 +137,4 @@ Keep this command running throughout the rest of this guide so it will reload al
137137

138138
## What's next?
139139

140-
In this chapter we we created a new Feathers application. To learn more about the generated files and what you can do with the CLI, have a look at the CLI guide after finishing the Getting Started guide. In [the next chapter](./services.md) we will learn more about Feathers services and databases.
140+
In this chapter, we've created a new Feathers application. To learn more about the generated files and what you can do with the CLI, have a look at the [CLI guide](../cli/index.md) after finishing the Getting Started guide. In [the next chapter](./services.md) we will learn more about Feathers services and databases.

docs/guides/basics/hooks.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -67,18 +67,19 @@ The hook `context` is an object which contains information about the service met
6767

6868
Read-only properties are:
6969

70-
- `context.app` - The Feathers application object. This can be used to e.g. call other services
71-
- `context.service` - The service this hook is currently running on
70+
- `context.app` - The Feathers application object. This commonly used to call other services
71+
- `context.service` - The service object this hook is currently running on
7272
- `context.path` - The path (name) of the service
73-
- `context.method` - The service method name
74-
- `context.type` - The hook type
73+
- `context.method` - The name of the service method being called
74+
- `context.type` - The hook type (around, before, etc)
7575

7676
Writeable properties are:
7777

7878
- `context.params` - The service method call `params`. For external calls, `params` usually contains:
79-
- `context.params.query` - The query (e.g. from the query string) for the service call
80-
- `context.params.provider` - The name of the transport the call has been made through. Usually `rest` or `socketio`. Will be `undefined` for internal calls.
81-
- `context.id` - The `id` for a `get`, `remove`, `update` and `patch` service method call
79+
- `context.params.query` - The query filter (e.g. from the REST query string) for the service call
80+
- `context.params.provider` - The name of the transport the call has been made through. Usually `"rest"` or `"socketio"`. Will be `undefined` for internal calls.
81+
- `context.params.user` - *If authenticated*, the data of the user making the service method call.
82+
- `context.id` - The `id` of the record if the service method call is a `get`, `remove`, `update` or `patch`
8283
- `context.data` - The `data` sent by the user in a `create`, `update` and `patch` and custom service method call
8384
- `context.error` - The error that was thrown (in `error` hooks)
8485
- `context.result` - The result of the service method call (available after calling `await next()` or in `after` hooks)
@@ -172,7 +173,7 @@ declare module '../../declarations' {
172173
}
173174
```
174175

175-
Now every time a our messages service is accessed successfully the name, method and runtime will be logged.
176+
Now every time a our messages service is accessed successfully, the name, method and runtime will be logged.
176177

177178
<BlockQuote type="tip">
178179

docs/guides/basics/schemas.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,27 @@ In Feathers, schemas and resolvers allow us to define, validate and secure our d
66

77
As we've briefly seen in the [previous chapter about hooks](./hooks.md), there were a few hooks registered already to validate schemas and resolve data. Schema validators and resolvers are used with those hooks to modify data in the hook context. Similar to how Feathers services are transport independent, schemas and resolvers are database independent. It comes in two main parts:
88

9-
- [TypeBox](../../api/schema//typebox.md) or [JSON schema](../../api/schema//schema.md) to define a schema. This allows us to do things like:
9+
- [TypeBox](../../api/schema/typebox.md) or [JSON schema](../../api/schema/schema.md) to define a schema. This allows us to do things like:
1010
- Ensure data is valid and always in the right format
1111
- Automatically get up to date TypeScript types from schema definitions
1212
- Create a typed client that can be used in React, Vue etc. apps
1313
- Automatically generate API documentation
14-
- Validate query string queries and convert them to the correct type
14+
- Validate query string filters and convert them to the correct types
1515
- [Resolvers](../../api/schema/resolvers.md) - Resolve schema properties based on a context (usually the [hook context](./hooks.md)). This can be used for many different things like:
1616
- Populating associations
17-
- Securing queries and e.g. limiting requests to the logged in user
17+
- Securing queries and limiting the type of requests the logged in user can perform
1818
- Safely hiding sensitive data for external clients
19-
- Adding read- and write permissions on the property level
19+
- Adding read and write permissions on the property field level
2020
- Hashing passwords and validating dynamic password policies
2121

2222
In this chapter we will look at the generated schemas and resolvers and update them with the information we need for our chat application.
2323

2424
## Feathers schemas
2525

26-
While schemas and resolvers can be used outside of a Feather application, you will usually encounter them in a Feathers context where they come in four kinds:
26+
While schemas and resolvers can be used outside of a Feathers application, you will usually encounter them in a Feathers context where they come in four kinds:
2727

2828
- **Result** schemas and resolvers that define the data that is being returned. This is also where associated data would be fetched
29-
- **Data** schemas and resolvers handle the data from the `create`, `update` and `patch` service methods and can be used to add things like default or calculated values (like the created or updated at date) before saving to the database
29+
- **Data** schemas and resolvers handle the data from a `create`, `update`, `patch`, or custom service method and can be used to add/replace things like default or calculated values (e.g. the createdAt/updatedAt date) before saving it to the database
3030
- **Query** schemas and resolvers validate and convert the query string and can also be used for additional limitations like only allowing a user to see and modify their own data
3131
- **External** resolvers that return a safe version of the data (e.g. hiding a users password) that can be sent to external clients
3232

@@ -244,7 +244,7 @@ export const userQueryResolver = resolve<UserQuery, HookContext>({
244244

245245
## Handling messages
246246

247-
Next we can look at the messages service schema. We want to include the date when the message was created as `createdAt` and the id of the user who sent it as `userId`. When we get a message back, we also want to populate the `user` with the user data from `userId` so that we can show e.g. the user image and email.
247+
Next we can look at the messages service schema. We want to include the date when the message was created as `createdAt` and the id of the user who sent it as `userId`. When we get a message back, we also want to populate the `user` with the user data from `userId` so that we can show their avatar and email.
248248

249249
<LanguageBlock global-id="ts">
250250

@@ -424,7 +424,7 @@ The `virtual()` in the `messageResolver` `user` property is a [virtual property]
424424

425425
<DatabaseBlock global-id="sql">
426426

427-
Now that our schemas and resolvers have everything we need, we also have to update the database with those changes. For SQL databases this is done with migrations. Migrations are a best practise for SQL databases to roll out and undo changes to the data model. Every change we make in a schema will need its corresponding migration step.
427+
Now that our schemas and resolvers have everything we need, we also have to update the database with those changes. For SQL databases this is done with migrations. Migrations are a best practice for SQL databases to roll out and undo changes to the data model. Every change we make in a schema will need its corresponding migration step.
428428

429429
<BlockQuote type="warning">
430430

@@ -498,4 +498,4 @@ For MongoDB no migrations are necessary.
498498

499499
## What's next?
500500

501-
In this chapter we learned about schemas and implemented all the things we need for our chat application. In the next chapter we will learn about [authentication](./authentication.md) and add a "Login with GitHub".
501+
In this chapter we learned about schemas and implemented all the things we need for our chat application. In the next chapter we will learn about [authentication](./authentication.md) and add a "Login with GitHub" button.

0 commit comments

Comments
 (0)