|
1 | | -# JSON:API for Dart/Flutter |
| 1 | +# JSON:API Client and Server for Dart/Flutter. Version 5. |
2 | 2 |
|
3 | | -[JSON:API] is a specification for building APIs in JSON. |
| 3 | +[JSON:API] is a specification for building JSON APIs. The documentation is a work-in-progress. |
4 | 4 |
|
5 | | -This package consists of several libraries: |
6 | | -- The [Document library] is the core of this package. It describes the JSON:API document structure |
7 | | -- The [Client library] is a JSON:API Client for Flutter, Web and Server-side |
8 | | -- The [Server library] is a framework-agnostic JSON:API server implementation |
9 | | -- The [HTTP library] is a thin abstraction of HTTP requests and responses |
10 | | -- The [Query library] builds and parses the query parameters (page, sorting, filtering, etc) |
11 | | -- The [Routing library] builds and matches URIs for resources, collections, and relationships |
12 | | - |
13 | | -## Document model |
14 | | -The main concept of JSON:API model is the [Resource]. |
15 | | -Resources are passed between the client and the server in the form of a JSON-encodable [Document]. |
16 | | - |
17 | | -## Client |
18 | | -[JsonApiClient] is an implementation of the JSON:API client supporting all features of the JSON:API standard: |
19 | | -- fetching resources and collections (both primary and related) |
20 | | -- creating resources |
21 | | -- deleting resources |
22 | | -- updating resource attributes and relationships |
23 | | -- direct modification of relationships (both to-one and to-many) |
24 | | -- [async processing](https://jsonapi.org/recommendations/#asynchronous-processing) |
25 | | - |
26 | | -The client returns back a [Response] which contains the HTTP status code, headers and the JSON:API [Document]. |
27 | | - |
28 | | -Sometimes the request URIs can be inferred from the context. |
29 | | -For such cases you may use the [RoutingClient] which is a wrapper over the [JsonApiClient] capable of inferring the URIs. |
30 | | -The [RoutingClient] requires an instance of [RouteFactory] to be provided. |
31 | | - |
32 | | -[JsonApiClient] itself does not make actual HTTP calls. |
33 | | -Instead, it calls the underlying [HttpHandler] which acts as an HTTP client (must be passed to the constructor). |
34 | | -The library comes with an implementation of [HttpHandler] called [DartHttp] which uses the Dart's native http client. |
35 | | - |
36 | | -## Server |
37 | | -This is a framework-agnostic library for implementing a JSON:API server. |
38 | | -It may be used on its own (a fully functional server implementation is included) or as a set of independent components. |
39 | | - |
40 | | -### Request lifecycle |
41 | | -#### HTTP request |
42 | | -The server receives an incoming [HttpRequest] containing the HTTP headers and the body represented as a String. |
43 | | -When this request is received, your server may decide to check for authentication or other non-JSON:API concerns |
44 | | -to prepare for the request processing, or it may decide to fail out with an error response. |
45 | | - |
46 | | -#### JSON:API request |
47 | | -The [RequestConverter] is then used to convert the HTTP request to a [JsonApiRequest]. |
48 | | -[JsonApiRequest] abstracts the JSON:API specific details, |
49 | | -such as the request target (a collection, a resource or a relationship) and the decoded body (e.g. [Resource] or [Identifier]). |
50 | | -At this point it is possible to determine whether the request is a valid JSON:API request and to read the decoded payload. |
51 | | -You may perform some application-specific logic, e.g. check for authentication. |
52 | | -Each implementation of [JsonApiRequest] has the `handleWith()` method to dispatch a call to the right method of the [Controller]. |
53 | | - |
54 | | -#### Controller |
55 | | -The [Controller] consolidates all methods to process JSON:API requests. |
56 | | -Every controller method must return an instance of [JsonApiResponse] (or another type, the controller is generic). |
57 | | -This library comes with a particular implementation of the [Controller] called [RepositoryController]. |
58 | | -The [RepositoryController] takes care of all JSON:API specific logic (e.g. validation, filtering, resource |
59 | | -inclusion) and translates the JSON:API requests to calls to a resource [Repository]. |
60 | | - |
61 | | -#### Repository (optional) |
62 | | -The [Repository] is an interface separating the data storage concerns from the specifics of the API. |
63 | | - |
64 | | -#### JSON:API response |
65 | | -When an instance of [JsonApiResponse] is returned from the controller, the [ResponseConverter] |
66 | | -converts it to an [HttpResponse]. |
67 | | -The converter takes care of JSON:API transport-layer concerns. |
68 | | -In particular, it: |
69 | | -- generates a proper [Document], including the HATEOAS links or meta-data |
70 | | -- encodes the document to JSON string |
71 | | -- sets the response headers |
72 | | - |
73 | | -#### HTTP response |
74 | | -The generated [HttpResponse] is sent to the underlying HTTP system. |
75 | | -This is the final step. |
76 | | - |
77 | | -## HTTP |
78 | | -This library is used by both the Client and the Server to abstract out the HTTP protocol specifics. |
79 | | -The [HttpHandler] interface turns an [HttpRequest] to an [HttpResponse]. |
80 | | -The Client consumes an implementation of [HttpHandler] as a low-level HTTP client. |
81 | | -The Server is itself an implementation of [HttpHandler]. |
82 | | - |
83 | | -## Query |
84 | | -This is a set of classes for building avd parsing some URL query parameters defined in the standard. |
85 | | -- [Fields] for [Sparse fieldsets] |
86 | | -- [Include] for [Inclusion of Related Resources] |
87 | | -- [Page] for [Collection Pagination] |
88 | | -- [Sort] for [Collection Sorting] |
89 | | - |
90 | | -## Routing |
91 | | -Defines the logic for constructing and matching URLs for resources, collections and relationships. |
92 | | -The URL construction is used by both the Client (See [RoutingClient] for instance) and the Server libraries. |
93 | | -The [StandardRouting] implements the [Recommended URL design]. |
94 | 5 |
|
95 | 6 | [JSON:API]: https://jsonapi.org |
96 | | -[Sparse fieldsets]: https://jsonapi.org/format/#fetching-sparse-fieldsets |
97 | | -[Inclusion of Related Resources]: https://jsonapi.org/format/#fetching-includes |
98 | | -[Collection Pagination]: https://jsonapi.org/format/#fetching-pagination |
99 | | -[Collection Sorting]: https://jsonapi.org/format/#fetching-sorting |
100 | | -[Recommended URL design]: https://jsonapi.org/recommendations/#urls |
101 | | - |
102 | | -[Client library]: https://pub.dev/documentation/json_api/latest/client/client-library.html |
103 | | -[Server library]: https://pub.dev/documentation/json_api/latest/server/server-library.html |
104 | | -[Document library]: https://pub.dev/documentation/json_api/latest/document/document-library.html |
105 | | -[Query library]: https://pub.dev/documentation/json_api/latest/query/query-library.html |
106 | | -[Routing library]: https://pub.dev/documentation/json_api/latest/uri_design/uri_design-library.html |
107 | | -[HTTP library]: https://pub.dev/documentation/json_api/latest/http/http-library.html |
108 | | - |
109 | | - |
110 | | -[Resource]: https://pub.dev/documentation/json_api/latest/document/Resource-class.html |
111 | | -[Identifier]: https://pub.dev/documentation/json_api/latest/document/Identifier-class.html |
112 | | -[Document]: https://pub.dev/documentation/json_api/latest/document/Document-class.html |
113 | | -[JsonApiClient]: https://pub.dev/documentation/json_api/latest/client/JsonApiClient-class.html |
114 | | - |
115 | | - |
116 | | -[Response]: https://pub.dev/documentation/json_api/latest/client/Response-class.html |
117 | | -[RoutingClient]: https://pub.dev/documentation/json_api/latest/client/RoutingClient-class.html |
118 | | -[DartHttp]: https://pub.dev/documentation/json_api/latest/client/DartHttp-class.html |
119 | | - |
120 | | - |
121 | | -[RequestConverter]: https://pub.dev/documentation/json_api/latest/server/RequestConverter-class.html |
122 | | -[JsonApiResponse]: https://pub.dev/documentation/json_api/latest/server/JsonApiResponse-class.html |
123 | | -[ResponseConverter]: https://pub.dev/documentation/json_api/latest/server/ResponseConverter-class.html |
124 | | -[JsonApiRequest]: https://pub.dev/documentation/json_api/latest/server/JsonApiRequest-class.html |
125 | | -[Controller]: https://pub.dev/documentation/json_api/latest/server/Controller-class.html |
126 | | -[Repository]: https://pub.dev/documentation/json_api/latest/server/Repository-class.html |
127 | | -[RepositoryController]: https://pub.dev/documentation/json_api/latest/server/RepositoryController-class.html |
128 | | - |
129 | | - |
130 | | -[HttpHandler]: https://pub.dev/documentation/json_api/latest/http/HttpHandler-class.html |
131 | | -[HttpRequest]: https://pub.dev/documentation/json_api/latest/http/HttpRequest-class.html |
132 | | -[HttpResponse]: https://pub.dev/documentation/json_api/latest/http/HttpResponse-class.html |
133 | | - |
134 | | - |
135 | | -[Fields]: https://pub.dev/documentation/json_api/latest/query/Fields-class.html |
136 | | -[Include]: https://pub.dev/documentation/json_api/latest/query/Include-class.html |
137 | | -[Page]: https://pub.dev/documentation/json_api/latest/query/Page-class.html |
138 | | -[Sort]: https://pub.dev/documentation/json_api/latest/query/Sort-class.html |
139 | | - |
140 | | - |
141 | | -[RouteFactory]: https://pub.dev/documentation/json_api/latest/routing/RouteFactory-class.html |
142 | | -[StandardRouting]: https://pub.dev/documentation/json_api/latest/routing/StandardRouting-class.html |
0 commit comments