diff --git a/faq/index.md b/faq/index.md index 73f102746..28c0bc0e7 100644 --- a/faq/index.md +++ b/faq/index.md @@ -79,3 +79,30 @@ significant. It's necessary to separate primary and related resources by more than type because it's possible that a primary resource may have related resources of the same type (e.g. the "parents" of a "person"). Nesting related resources in `linked` prevents this possible conflict. + +### Since HTTP resources are already identified by URIs, why are `ID` and `type` required attributes? + +*Resource* is a core abstraction in both JSON API and HTTP [[RFC +7231](https://tools.ietf.org/html/rfc7231)]. The concepts are not equivalent, +however, and each specification has its own definition for the term. + +In HTTP, a resource is simply the service available at an HTTP endpoint. In order +to interact with it, *representations* are needed. JSON API provides structure +for those representations. + +An HTTP resource can be thought of as an interface (or a mapping) to a set of +underlying JSON API resources. An HTTP request always targets a single HTTP +resource but may affect any number of JSON API resources either in full or +partially. + +Importantly, the same JSON API resource may be exposed via several different HTTP +resources (URIs). An application is free to implement one-to-one correspondence +between JSON API resources and HTTP resources by always using unique canonical +URIs. But this is not required, and therefore an ID scheme is necessary. + +While JSON API resources often represent persistent objects that have a +meaningful ID, this need not be the case. For example, a server might provide an +authentication service (an HTTP resource) that returns instances of +authentication events (JSON API resources) that do not need an ID. In such a +situation, it is suggested that a UUID be generated for each resource object +originating at the server. diff --git a/format/index.md b/format/index.md index 8e18fc85c..ef640be72 100644 --- a/format/index.md +++ b/format/index.md @@ -7,8 +7,17 @@ title: "Format" ## Introduction -JSON API is a specification for how a client should request that resources be -fetched or modified, and how a server should respond to those requests. +JSON API is a specification for how an HTTP client should request that +resources be fetched or modified, and how an HTTP server should respond to +those requests. + +A *resource* is an entity that has *attributes* and may be associated with other +resources via *relationships*. JSON API does not impose constraints on what a +resource may represent. For example, a resource could describe an object in a +database, an event that has occurred, or the state of a service. + +> Note: JSON API and the HTTP specification do not share the same definition of +*resource*. For detailed information, see the [FAQ](/faq/#resources-ids). JSON API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies: