|
1 | | -[JSON:API](http://jsonapi.org) is a specification for building APIs in JSON. |
| 1 | +# JSON:API for Dart/Flutter |
| 2 | + |
| 3 | +[JSON:API] is a specification for building APIs in JSON. |
2 | 4 |
|
3 | 5 | This package consists of several libraries: |
4 | | -- The [Client] to make requests to JSON:API servers |
5 | | -- The [Server] which is still under development |
6 | | -- The [Document] model for resources, relationships, identifiers, etc |
7 | | -- The [Query] to build and parse the query parameters (pagination, sorting, etc) |
8 | | -- The [URL Design] to build and match URLs for resources, collections, and relationships |
9 | | - |
10 | | -[Client]: https://pub.dev/documentation/json_api/latest/client/client-library.html |
11 | | -[Server]: https://pub.dev/documentation/json_api/latest/server/server-library.html |
12 | | -[Document]: https://pub.dev/documentation/json_api/latest/document/document-library.html |
13 | | -[Query]: https://pub.dev/documentation/json_api/latest/query/query-library.html |
14 | | -[URL Design]: https://pub.dev/documentation/json_api/latest/url_design/url_design-library.html |
| 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 | + |
| 95 | +[JSON:API]: http://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