Skip to content

v2.3.0: local ids, extensions, and improved links and profiles (updating specification v1.1)
Compare
Choose a tag to compare
@lode lode released this 23 Aug 20:15
v2.3.0
6afd836
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Verified
Learn about vigilant mode.

This release makes updates to the new features of https://github.com/lode/jsonapi/releases/tag/v2.1.0, as the jsonapi specification v1.1 got changes (it is now at RC 3 and might still change, but the latest concepts are updated in this release).

Support local ids

Clients can now use a local id (lid) instead of an id. This is useful when the client wants to connect relationships to a resource not yet known by the server.

  • Added RequestParser->hasLocalId() and RequestParser->getLocalId() to check/get local ids from documents send by a client.
  • Added setLocalId() on a ResourceDocument, ResourceObject or ResourceIdentifierObject, for sending a local id as a client.

In a jsonapi document this will look like:

{
	"data": {
		"type": "user",
		"lid": "42"
	}
}

See #53 and the specification.

Changes for links

Link objects get a lot of new documented members. On a LinkObject you can now call:

  • ->setHumanTitle() to allow clients to add a human readable label to the link
  • ->setRelationType() for clarifying what kind of RFC 8288 relation type the target has
  • ->setMediaType() for clarifying which RFC 6838 media type the target has
  • ->addLanguage()/->setHreflang() for stating which RFC 5646 language(s) the target is in
  • ->setDescribedBy()/->setDescribedByLinkObject() for referencing to an JSON Scheme related to the link

Also, array links are deprecated. This caused confusion and wasn't used much.

  • deprecated ErrorObject->appendTypeLink(), use ErrorObject->setTypeLink() instead.
  • deprecated LinksObject->append()
  • deprecated LinksObject->addLinksArray()
  • deprecated LinksObject->appendLinkObject()

See #55, #62, the specification, the RFC 8288 relation types, the RFC 6838 media types, and the RFC 5646 language tags.

Changes for profiles and extensions

Customizing jsonapi was clarified. Profiles got better specification, and a concept of extensions got added. In short:

  • Profiles can be used to define meaning for existing undefined members inside the jsonapi document.
  • Extensions can be used to define new members inside the jsonapi document.

This release adds support for the Atomic Operations extension, and did updates to the Cursor Pagination profile.

  • Added Document->applyExtension()
  • Changed Document->applyProfile(): will add a profile to the root jsonapi object, and not to the root links object anymore.
  • Changed Document->setSelfLink(): will add an object if extensions/profiles are applied, where before only a string might be added.
  • Deprecated Profile->getKeyword(): aliasing of profile keywords got deprecated.
  • Deprecated Converter::mergeProfilesInContentType(): use Converter::prepareContentType() instead.

See #59, #47, #67, the specification for atomic operations, and the specification for cursor pagination.

Documenting JSON Scheme

It is now easier to document which JSON Scheme is used (for jsonapi or next to jsonapi).

  • Added Document->setDescribedByLink()

See #54.

Assets 2
Loading