You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api.md
+109-6Lines changed: 109 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -12,17 +12,89 @@ This uses the name `default` for your API and generates a config file called `js
12
12
13
13
### Multiple APIs
14
14
15
-
If your application has multiple APIs - e.g. if you've version controlled a public API - you must generate a config file for each API. For example:
15
+
If your application has multiple APIs - e.g. if you have a version controlled API - you must generate a config file for
16
+
each API. For example:
16
17
17
18
```bash
18
19
$ php artisan make:json-api v1
19
20
```
20
21
21
22
Will create the `json-api-v1.php` file.
22
23
24
+
## Namespacing
25
+
26
+
### Root Namespace
27
+
28
+
Your API's config file contains a `namespace` option that controls the namespace in which JSON API classes are held.
29
+
30
+
If `namespace` is `null`, the `JsonApi` namespace in your application's namespace will be used. E.g. in a default
31
+
Laravel installation, the namespace will be `App\JsonApi`. If you have renamed your application namespace to
32
+
`MyApp`, then `MyApp\JsonApi` will be used by default.
33
+
34
+
If you want to use a different namespace, set the `namespace` option accordingly. E.g. for our `v1` API, we might
35
+
want to set it to `App\JsonApi\V1`.
36
+
37
+
### Organising Resource Classes
38
+
39
+
The `by-resource` setting controls how you want to organise classes within this namespace. If this setting is `true`,
40
+
there will be a sub-namespace for each resource type. For example:
41
+
42
+
```text
43
+
App\JsonApi
44
+
- Posts
45
+
- Adapter
46
+
- Schema
47
+
- Comments
48
+
- Adapter
49
+
- Schema
50
+
```
51
+
52
+
If `by-resource` is `false`, the sub-namespace will be the class type (e.g. `Adapters`). For example:
53
+
54
+
```text
55
+
App\JsonApi
57AE
56
+
- Adapters
57
+
- Post
58
+
- Comment
59
+
- Schemas
60
+
- Post
61
+
- Comment
62
+
```
63
+
64
+
You must stick to whatever pattern you choose to use. This is because we use the structure to automatically detect
65
+
JSON API classes.
66
+
67
+
### Eloquent
68
+
69
+
The config also contains a `use-eloquent` option. Set this to `true` if the majority of your resources relate to
70
+
Eloquent models.
71
+
72
+
This option is used by the package's generators, so that they know to generate Eloquent JSON API classes or not. This
73
+
saves you having to specify the type whenever generating JSON API classes.
74
+
75
+
The `use-eloquent` option is effectively a default, and can be overridden when using a generator. For example, if
76
+
`use-eloquent` is `true`:
77
+
78
+
```bash
79
+
# will generate Eloquent classes
80
+
$ php artisan make:resource posts
81
+
# will generate non-Eloquent classes
82
+
$ php artisan make:resource posts -N
83
+
```
84
+
85
+
If `use-eloquent` is `false`:
86
+
87
+
```bash
88
+
# will generate non-Eloquent classes
89
+
$ php artisan make:resource posts
90
+
# will generate Eloquent classes
91
+
$ php artisan make:resource posts -e
92
+
```
93
+
23
94
## Defining Resources
24
95
25
-
Your API must be configured to understand how a JSON API resource type maps to a PHP class within your application. This is defined in the `resources` setting in the API's configuration file.
96
+
Your API must be configured to understand how a JSON API resource type maps to a PHP class within your application.
97
+
This is defined in the `resources` setting in the API's configuration file.
26
98
27
99
For example, if your application had two Eloquent models - `Post` and `Comment` - your resource configuration would be:
28
100
@@ -35,6 +107,41 @@ For example, if your application had two Eloquent models - `Post` and `Comment`
35
107
]
36
108
```
37
109
110
+
## URL
111
+
112
+
Each JSON API is expected to have a root URL under which all its routes are nested. This is configured in your API's
113
+
configuration file under the `url` setting, that looks like this:
114
+
115
+
```php
116
+
'url' => [
117
+
'host' => null,
118
+
'namespace' => '/api/v1',
119
+
'name' => 'api:v1:',
120
+
],
121
+
```
122
+
123
+
These settings control the links that appear in JSON API documents. We also automatically apply them when you
124
+
register routes for your API.
125
+
126
+
### Host
127
+
128
+
When processing inbound HTTP requests, the current server host will always be used when encoding JSON API documents.
129
+
130
+
When encoding JSON API documents outside of HTTP requests, we use the `url.host` option from your API's configuration.
131
+
If the value is `null`, we default to Laravel's `app.url` config setting. Otherwise, we'll use the value you've
132
+
provided.
133
+
134
+
### Namespace
135
+
136
+
The URL namespace is the URL under which all resources for the API are nested. For example, if the namespace is
137
+
`/api/v1`, then the `posts` resource routes will exists at `/api/v1/posts`.
138
+
139
+
### Name
140
+
141
+
The `name` setting applies the specified prefix to all route names that are registered for JSON API resources. For
142
+
example, if the `name` is `api:v1:`, then the route name for the index of the `posts` resource will be
143
+
`api:v1:posts.index`.
144
+
38
145
## Content Negotiation
39
146
40
147
The JSON API spec defines [content negotiation](http://jsonapi.org/format/#content-negotiation) that must occur
@@ -66,7 +173,3 @@ In the example, the config tells the codec matcher that the `application/vnd.api
66
173
In the example, the config tells the codec matcher that the `application/vnd.api+json` is the only acceptable
67
174
`Content-Type` that a client can submit. If a different media type is received, a `415 Unsupported Media Type`
68
175
response will be sent.
69
-
70
-
## Other Configuration Settings
71
-
72
-
The generated API configuration file contains descriptions of each setting. The wiki will cover these settings in the relevant chapter.
Copy file name to clipboardExpand all lines: docs/index.md
-12Lines changed: 0 additions & 12 deletions
Original file line number
Diff line number
Diff line change
@@ -37,18 +37,6 @@ Optionally you can also add an **Authorizer** instance to authorize incoming JSO
37
37
38
38
This may sound like a lot of units, but we believe the single purpose approach makes these highly testable and easy to reason about!
39
39
40
-
### Namespacing
41
-
42
-
JSON API units are expected to be stored in a root namespace, which defaults to the `JsonApi` namespace in your application - e.g. `App\JsonApi`.
43
-
44
-
We expect you to store units within this namespace in one of two ways:
45
-
46
-
1.**By Resource**: You have a namespace per resource type and the units for the type are stored in this namespace. E.g. for a `posts` resource you would have `App\JsonApi\Posts\{Adapter,Schema...}`
47
-
48
-
2.**By Unit**: You have a namespace per JSON API unit, with the classes named according to the the resource type. E.g. for a `posts` resource you would have `App\JsonApi\{Adapters,Schemas...}\Post`
49
-
50
-
For both, note that the namespace is plural, and the class name is singular. The package includes generator Artisan commands to keep this simple.
51
-
52
40
### Why *Records* not *Models*?
53
41
54
42
In Laravel the phrase *model* is potentially confusing with Eloquent models. While some applications might solely encode Eloquent models to JSON API resources, others will use a mixture of Eloquent models and other PHP classes, or might not even be using Eloquent models.
0 commit comments