Install
Works with Drupal: 8.xUsing Composer to manage Drupal site dependencies
Alternative installation files
Release notes
This is the first stable release of JSON:API 2.x π
Definitely read the announcement blog post by module founder @e0ipso: https://humanbits.es/web-development/2019/01/07/jsonapi-2/ π
Unlike many module major version bumps, 2.x does not mean that we rewrote the module! In fact, we've increased the stability of this module π―π€π₯
So, why has the major version been bumped? While making the module more specification compliant, and while adding more tests, and while covering more edge cases, we ran into a few things that we couldn't make better without breaking some things...
What did we break? Well, we've tried very hard to document each and every change. 90% of JSON:API clients won't need to change anything, backward compatibility was only broken in edge cases. We think you'll be okay with them π and we're pretty confident that the most disruptive changes have a relatively simple upgrade path. The most disruptive change is probably that Drupal's UNIX timestamps are now exposed as ISO timestamps via JSON:API.
We know what you're thinking, "alright, you've convinced me!" If you're having trouble figuring out how to upgrade, please file a "support request" so that we can improve the change record with more thorough instructions. We're happy to help you, if you'll help us find those cases π
This release includes a few new features over the 1.x branch and countless under-the-hood improvements that will allow us to ship new features for years to come:
- Entities that you are not allowed to view, but you are allowed to view the label of are no longer omitted; instead you can only see their label!
- the new
meta.links.me
entry provided by/jsonapi
which links to the current user - Significantly faster performance for includes and sparse fieldsets.
- Error responses are now cacheable, resulting in better scalability.
And for those of you thinking, "oh man, I just can't upgrade right now", we've tried to think of you too π€. JSON:API 1.22 marked the beginning of a "critical support" phase for the 1.x branch. We'll do our best to backport any security fixes and/or critical bugs affecting all users to the 1.x branch for a while yet.
We hope you love JSON:API as much as we do. Please consider filing an "experience report" in the issue queue to tell us how you're using it or what you've built with it, especially your successes! Believe it or not, we seem to only see your problems! Β―\_(γ)_/Β―
β€οΈβ€οΈβ€οΈ
- The JSON:API Maintainers π
API-first Drupal with multiple consumers @DrupalConNA :D pic.twitter.com/GhgY8O5SSa
β GΓ‘bor Hojtsy (@gaborhojtsy) April 11, 2018
Summary: 8.x-2.0
Contributors: (8) Wim Leers, gabesullice, Niklan, ndobromirov, joelstein, joshua.boltz, govind.maloo, dww
Issues: 7 issues resolved.
Changes since 8.x-2.0-rc4:
Bug
- #3021194 by Wim Leers, gabesullice, Niklan: [upstream] PATCHing DateTime field results in fatal error
- #3017945 by Wim Leers, ndobromirov: [upstream] Field types with a required property *and* an optional @DataType=datetime_iso8601 property trigger fatal error in DateTimeNormalizer when optional property is empty
- #2999438 by Wim Leers, joelstein, joshua.boltz: [upstream] Datetime field shown with wrong timezone offset
Task
- #2992673 by Wim Leers: Set collection-specific query parameter cache contexts on collection responses instead of all responses
- #3021873 by govind.maloo, dww: Two nits in jsonapi.api.php
- #3021728 by Wim Leers: After SA-CONTRIB-2018-081, automated tests soft-failing due to CS violations
Summary: 8.x-2.0
Contributors: (63) Wim Leers, gabesullice, Niklan, ndobromirov, joelstein, joshua.boltz, govind.maloo, dww, effulgentsia, tstoeckler, amateescu, e0ipso, hchonov, dawehner, berdir, kristiaanvandeneynde, larowlan, dagmar, yobottehg, olexyy.mails@gmail.com, keesee, caseylau, peterdijk, jibran, mortona2k, jludwig, pixelwhip, abhisekmazumdar, izus, Mile23, garphy, btully, mglaman, steven.wichers, omkar06, haihoi2, axle_foley00, hampercm, clemens.tolboom, gargsuchi, justafish, sonnykt, alexpott, jlscott, DavidSpiessens, BR0kEN, danielnv18, drpal, martin107, webchick, balsama, nileshlohar, gerzenstl, mgalalm, tedbow, Grimreaper, das-peter, pwolanin, skyredwang, Dave Reid, mstef, bwinett
Issues: 160 issues resolved.
Changes since 8.x-1.22:
Bug
- #3021194 by Wim Leers, gabesullice, Niklan: [upstream] PATCHing DateTime field results in fatal error
- #3017945 by Wim Leers, ndobromirov: [upstream] Field types with a required property *and* an optional @DataType=datetime_iso8601 property trigger fatal error in DateTimeNormalizer when optional property is empty
- #2999438 by Wim Leers, joelstein, joshua.boltz: [upstream] Datetime field shown with wrong timezone offset
- #3015759 by gabesullice, Wim Leers, dagmar: `?filter[drupal_internal__id]=ID` does not work: drupal_internal__id should not be converted to uuid when filtering
- #3016866 by e0ipso, gabesullice, Wim Leers: The "me" link breaks the EntryPoint when user resource is internal
- #3014380 by olexyy.mails@gmail.com, Wim Leers, keesee, caseylau: EntityReference base fields that are optional are not empty, but its sole item is empty, causing EntityReferenceFieldNormalizer to fail
- #3010432 by gabesullice, Wim Leers, effulgentsia, peterdijk, e0ipso: Filtering by referenced entity requires ".uuid" to be specified in filter path expression
- #3007113 by Wim Leers, gabesullice: Follow-up for #2977669: denormalizing aliased relationships fails
- #3005826 by jludwig, Wim Leers: Follow-up for #2984964: JSON API + hook_node_grants() implementations: count queries still result in cacheability metadata leak
- #2986900 by e0ipso: Unnecessary asserts break installation in distros that include JSON API
- #2984886 by Wim Leers, gabesullice, e0ipso: Trigger route rebuild when new bundles/fields are added/removed
- #2996000 by gabesullice, Wim Leers: Deduplicate `meta.omitted.links` based on `href` (`via` link)
- #2984647 by Wim Leers, haihoi2, gabesullice, dawehner: Dangling entity references in entity reference field with multiple possible target bundles: results in exception/500 response
- #2995111 by Wim Leers, e0ipso: shouldBeInternalResourceType et al. should receive the resource type, not the entity type
- #2853066 by gabesullice, Wim Leers, e0ipso, hampercm, clemens.tolboom, dawehner: Spec Compliance: Inaccessible collection/related resources surface errors: should be 200 with hypermedia + metadata
- #2977659 by gabesullice, Wim Leers: Spec Compliance: POST|PATCH|DELETE on relationships should respect arity rules
- #2977600 by Wim Leers, gabesullice, e0ipso: Spec Compliance: `_format` is a disallowed query parameter name
- #2949807 by Wim Leers, gabesullice: Spec Compliance: Error responses are missing the `jsonapi` top-level member
- #2985426 by gabesullice, Wim Leers: Spec compliance: `related` routes should return 200, not 403, if field access is allowed but the related resources are forbidden
- #2990552 by gabesullice: Followup to #2986383: Custom content blocks are now reusable in 8.6 also
- #2990532 by gabesullice: Drupal core compatibility: Terms are now publishable in 8.6+
- #2986899 by gabesullice: Drupal core compatibility: SchemaIncompleteException for some config entity types
- #2977669 by Wim Leers, gargsuchi, gabesullice, e0ipso, justafish, sonnykt: Spec Compliance: some entity types have an "id", "type" or "uuid" field, this violates the spec
- #2942549 by gabesullice, Wim Leers: Spec Compliance: JSON API allows POSTing relationship fields in 'attributes' rather than in 'relationships'
- #2986383 by gabesullice: Drupal core compatibility: Block content entities have a `reusable` field in 8.7+
- #2984964 by Wim Leers, jlscott, DavidSpiessens, gabesullice: JSON API + hook_node_grants() implementations: accessing /jsonapi/node/article as non-admin user results in a cacheability metadata leak
- #2984494 by sonnykt, Wim Leers, gabesullice: EntityResource calls `$entity->get('field_name')` without first ensuring the entity is a fieldable entity
- #2955615 by Wim Leers, gabesullice, e0ipso: Field properties are not being denormalized
- #2934149 by Wim Leers, gabesullice: [>=8.5] JSON API routes not specifying _content_type_format route requirement, resulting in bad DX
- #2982478 by Wim Leers, gabesullice: JsonApiRequestValidator creates ResourceResponse object with array instead of JsonApiDocumentTopLevelNormalizerValue
- #2933062 by Wim Leers, gabesullice: [>=8.5.4] Spec Compliance: Return 400 for unrecognized/unsupported query parameters
- #2977653 by Wim Leers, gabesullice: Spec Compliance: Return 204 or 200, not 201 for relationship POST requests
- #2974297 by mgalalm, Wim Leers, gabesullice: JSON API Extras regression introduced by www.drupal.org/node/2939729">#2939729: "related" links no longer shown for aliased relationship fields
- #2968972 by axle_foley00, Wim Leers, gabesullice, garphy: Cannot PATCH an entity with dangling references in an ER field
- #2978417 by gabesullice: PHP 5.5 syntax error, unexpected '->'
- #2977879 by Wim Leers, gabesullice: Regression in #2940339: when multiple vocabularies exist, normalization of Terms fails
- #2966384 by Wim Leers: JSON API's LinkManager does not handle cacheability correctly, just like its origin (HAL's LinkManager)
- #2976108 by Wim Leers, gabesullice: Spec Compliance: Impossible to include related resources when relationship field is not in a request's sparse fieldset
- #2976371 by gabesullice, Wim Leers: Impossible to POST|PATCH relationship to bundle-less entity or entity reference field without target bundles
- #2976053 by Wim Leers: JSON API fails on 8.6 (since #2938035 + #1252606)
- #2973681 by caseylau, gabesullice, Wim Leers, e0ipso: Regression introduced by www.drupal.org/node/2953207">#2953207: Deep nested include on multi target entity type field fail
- #2973916 by gabesullice, Wim Leers: Impossible to filter using path specifier with entity type
- #2864680 by Wim Leers, Grimreaper, gabesullice: Spec Compliance: JSON API's schema disallows duplicate resource identifiers. EntityReferenceItems which reference the same entity must have an "arity"
- #2973151 by e0ipso, das-peter, Wim Leers: Composer dependency issue: justinrainbow/json-schema
- #2944977 by Wim Leers, gabesullice: Message entities can only be created (POSTed), they cannot be read or modified
- #2972107 by pwolanin, Wim Leers: JSON API's RequestHandler causes fatal PHP error when a GET request has a body
- #2953207 by Wim Leers, gabesullice, caseylau, skyredwang: Can't get the right target type when filtering on relationship with bundle-specific target entity type
- #2946746 by Wim Leers, jlscott, pwolanin, gabesullice, e0ipso: Unhandled exceptions/fatal errors when POST/PATCH documents contain unknown field names
- #2958587 by gabesullice, Wim Leers, Dave Reid: Unable to filter on columns of entity reference fields
- #2943170 by Wim Leers, e0ipso, gabesullice: JSON API's RequestHandler causes fatal PHP error when a PATCH or POST request has no body
- #2959445 by Wim Leers, caseylau, gabesullice: Entity querying config entities does not work, so neither does JSON API collection filtering: provide helpful DX
- #2961562 by gabesullice, Wim Leers, bwinett: JSON API 1.15 uses code available in Drupal core >=8.4.3, but requires only >=8.3
- #2958166 by caseylau, Wim Leers, gabesullice: Traversable Object with custom normalizer can't be right normalized
Feature
- #2986484 by e0ipso, Wim Leers: Add verbose logging to failed assertions for base path
- #2927037 by Wim Leers, danielnv18, gabesullice, e0ipso: Provide a mechanism to get information about the current user: "me" meta link in /jsonapi, and make /jsonapi accessible to all
- #2843922 by drpal, Wim Leers, hampercm, e0ipso, gabesullice: Show label of inaccessible entities ('view' access denied) when 'view label' access is allowed
- #2949632 by Wim Leers, e0ipso, gabesullice: Make ResourceTypeRepository aware of the path prefix
- #2968891 by Wim Leers, mstef, gabesullice: Allow extreme shorthand filtering: ?filter[promote]=1
Task
- #2992673 by Wim Leers: Set collection-specific query parameter cache contexts on collection responses instead of all responses
- #3021873 by govind.maloo, dww: Two nits in jsonapi.api.php
- #3021728 by Wim Leers: After SA-CONTRIB-2018-081, automated tests soft-failing due to CS violations
- #3021277 by gabesullice, Wim Leers: Test failures on 8.7 since #2869426
- #3019574 by gabesullice, Wim Leers: JSON:API 1.1 RC1 Spec Compliance: Creating/updating a relationship to a non-existant resource should 404
- #3019389 by Wim Leers: MediaTest fails on 8.7 since #2956368
- #3019506 by Wim Leers, gabesullice: UserTest::testRelated() fails on Drupal 8.5 because no $reason is given in the Access Denied response
- #3014232 by ndobromirov, gabesullice, Wim Leers, yobottehg, e0ipso: [regression] ResourceTypeRepository is significantly slower in JSON:API 2, becomes noticeable when handling hundreds of interlinked resources
- #3017239 by ndobromirov, gabesullice, Wim Leers, e0ipso: Optimize ResourceTypeRepository::get(): don't loop over all possible resource types in every call
- #3001193 by gabesullice, Wim Leers: CommentTest::testPostIndividualDxWithoutCriticalBaseFields() fails on 8.7 since #2885809
- #3015343 by Wim Leers: Follow-up for #3007274: s/JSON API/JSON:API/ in *.module files
- #3014289 by gabesullice, Wim Leers: VocabularyTest is broken by Drupal core >= 8.7 which removed the `hierarchy` key
- #3009596 by gabesullice, Wim Leers, yobottehg, jibran, mortona2k: JSON API 2.x responses always result in a Page Cache MISS
- #3007274 by Wim Leers, gabesullice, e0ipso: s/JSON API/JSON:API/
- #3011099 by jibran, Wim Leers, e0ipso, gabesullice: Only serialize sparse_fieldset fields in \Drupal\jsonapi\Normalizer\EntityNormalizer::normalize()
- #3008544 by Wim Leers, gabesullice: Use \Drupal\serialization\Normalizer\CacheableNormalizerInterface::SERIALIZATION_CONTEXT_CACHEABILITY
- #3005999 by gabesullice, Wim Leers, e0ipso: Revision ID should be `drupal_internal__vid`
- #3006743 by Wim Leers: Follow-up for #2624770: EntityConverter service requires additional parameters since Drupal core 8.7
- #3006270 by Wim Leers: Add ResourceTypeRepository::createResourceType() for easier JSON API Extras support and simpler code
- #2946537 by Wim Leers, gabesullice, pixelwhip: Test coverage: Inclusion of intermediate resources when include is a multi-part relationship path
- #2956084 by gabesullice, Wim Leers: Impossible to raise an error when an `include` is requested for an inaccessible relationship field
- #3003148 by abhisekmazumdar, gabesullice, izus: README should point to jsonapi.api.php and online documentation
- #2991841 by gabesullice, Wim Leers: Remove unused parameters from EntityResource methods
- #2987610 by gabesullice, Wim Leers: Remove RequestHandler class and service and add EntityResource methods to each route definition
- #2987608 by gabesullice, Wim Leers: Move deserialization from RequestHandler to JsonApiParamEnhancer
- #3001564 by gabesullice, Wim Leers: Follow-up to #2997600: Clean up dead code paths
- #3001958 by Wim Leers, gabesullice, Mile23: 4 test fails due to using deprecated code on 8.6 and 8.7 since #2996789: temporarily fork the test trait
- #2997277 by gabesullice, Wim Leers, garphy, e0ipso: Place all URLs under the `href` key
- #3000622 by Wim Leers, gabesullice: Improve EntryPoint::index() now that JsonApiDocumentTopLevel is more capable
- #2997600 by gabesullice, Wim Leers, caseylau, e0ipso, btully, mglaman, steven.wichers: Resolve included resources prior to normalization
- #3000299 by Wim Leers: Let phpcs violations fail the build on DrupalCI
- #2998601 by gabesullice, Wim Leers: HEAD is failing tests for various reasons
- #2987606 by Wim Leers, gabesullice, e0ipso, omkar06: Remove config mutation tests from EntityResourceTest
- #2984911 by Wim Leers, gabesullice, e0ipso: Remove access to the Request object in the normalization process
- #2996576 by gabesullice: Coding Standards: Back to 0 violations
- #2987609 by gabesullice, Wim Leers, e0ipso: Rename the entity parameter from the entity type ID to 'entity' for all routes
- #2994480 by gabesullice: Followup to #2853066: convert internal `meta.errors` to `meta.omitted`
- #2929428 by Wim Leers, gabesullice, axle_foley00: [>=8.5] Convert "throw new *HttpException" into "throw new Cacheable*HttpException" where possible
- #2986404 by Wim Leers: @FieldType=map support
- #2994700 by gabesullice, Wim Leers: Remove unused argument from the link manager
- #2936754 by Wim Leers, e0ipso, gabesullice: Avoid using the Serialization component for JSON API specific tasks
- #2994479 by gabesullice: Followup to #2934362: remove 'code' in most cases
- #2987205 by Wim Leers, e0ipso: FormatSetter doesn't set the format to `api_json` when accessing just `/jsonapi`
- #2991389 by gabesullice, Wim Leers: Test coverage: relationship response cacheabiliity
- #2987604 by gabesullice, Wim Leers: Turn EntityResource into a service
- #2987603 by gabesullice, Wim Leers: Make resource type an explicit parameter to each EntityResource method
- #2987206 by gabesullice, Wim Leers: Refactor `getEntityAndAccess` to return cacheable objects with access cacheability rather than an entity/access pair
- #2986987 by gabesullice, Wim Leers, e0ipso: Convert EntityAccessDeniedHttpException into cacheable exception
- #2982479 by alexpott, gabesullice, justafish, Wim Leers: Handle entities with no bundle in ResourceTypeRepository
- #2985321 by Wim Leers: Follow-up for #2929932: two @todos left for that issue that actually already have been addressed
- #2953346 by gabesullice, Wim Leers, BR0kEN: Define related/relationship routes per field, not dynamically (with route parameters that need validating)
- #2984607 by Wim Leers, gabesullice: Remove Drupal core <8.5 BC layer code and require Drupal >=8.5
- #2973784 by Wim Leers, gabesullice, e0ipso: JSON API should check entity access during routing, not in controller, for the "individual" route
- #2983631 by martin107: Update @throws documentation in the EntityResource class
- #2983196 by Wim Leers: Fix all deprecation errors in Drupal 8.6
- #2983051 by Wim Leers: Allow ResourceResponseValidatorTest to run non-schemata tests when schemata is not installed
- #2982964 by Wim Leers: Add a drupalci.yml to JSON API to match Drupal core's and fix all surfaced deprecation errors
- #2929932 by Wim Leers, e0ipso, gabesullice: Work around core's ill-designed @FieldType-level TimestampItemNormalizer normalization until #2926508 lands
- #2957474 by Wim Leers, gabesullice, e0ipso, effulgentsia, dawehner, webchick, balsama, drpal: Move the write functionality of config entities to a sub-module in preparation for removal
- #2971040 by Wim Leers, nileshlohar, gabesullice: PHP 7.1 Compatibility Warning
- #2982210 by Wim Leers: Move EntityToJsonApi service to JSON API Extras
- #2957271 by gabesullice, Wim Leers: [>=8.5] Fix RouteEnhancerInterface deprecation errors
- #2933895 by Wim Leers, gabesullice, e0ipso: [>=8.5] Update type hint to interface instead of concrete class in FieldResolver
- #2926463 by Wim Leers, garphy, e0ipso: [>=8.5] Remove JSON API's "file URL" field work-around now that Drupal core 8.5 fixed it
- #2971745 by Wim Leers, gabesullice, gerzenstl, e0ipso: Don't hardcode `/jsonapi/` in FormatSetter, read JSON API base path from container parameter instead
- #2948666 by Wim Leers, gabesullice: Remove JSON API's use of $context['cacheable_metadata']
- #2962461 by Wim Leers, gabesullice: JsonApiDocumentTopLevelNormalizer is SerializerAware but doesn't get the serializer injected
- #2980593 by Wim Leers, gabesullice: Follow-up for #2977879: remove work-around for #2977882
- #2980298 by gabesullice, tedbow: Coding Standards: Back to 0 violations
- #2972808 by gabesullice, Wim Leers: Comprehensive JSON API integration test coverage phase 6: POST/PATCH/DELETE of relationships
- #2976909 by gabesullice: Follow-up for #2953321; fixes PHP 5.5 test failure
- #2940339 by Wim Leers, gabesullice: Port reference field support for non-empty entity reference fields not pointing to an entity from #2543726
- #2953321 by gabesullice, Wim Leers, pixelwhip: Comprehensive JSON API integration test coverage phase 5: nested includes and sparse field sets
- #2897257 by Wim Leers, Grimreaper, gabesullice: Add test coverage to ensure it's possible to reference File entities
- #2942561 by Wim Leers: Assert denormalizing the JSON API response results in the expected object
- #2953318 by gabesullice, Wim Leers: Comprehensive JSON API integration test coverage phase 4: collections, filtering and sorting
- #2973322 by gabesullice, Wim Leers: Coding Standards: back to 0 violations
- #2971649 by gabesullice, Wim Leers: Make '_is_jsonapi' route option a route default
- #2932679 by gabesullice, Wim Leers: Remove unused "on_relationship" serialization context
- #2971562 by gabesullice, Wim Leers: Refactor/clean-up Routes.php
- #2971277 by Wim Leers: FileTest::testPatchIndividual() and FileTest::testDeleteIndividual() failing on 8.6
- #2962443 by gabesullice, Wim Leers: Remove route object and route requirements access
- #2859207 by Wim Leers, gabesullice, dawehner: Move Drupal\jsonapi\EventSubscriber\ResourceResponseSubscriber::validateResponse() to its own subscriber
- #2969493 by Wim Leers: MediaTest::testPatchIndividual() and MediaTest::testDeleteIndividual() failing on 8.6
- #2968015 by gabesullice: Break out ResourceTestBase field-related setUp into separate method
- #2968019 by gabesullice: EntityViewDisplayTest::testGetIndividual() failing on 8.6
- #2966363 by Wim Leers: CommentTest::testPatchIndividual() failing on 8.6
- #2957274 by Wim Leers, gabesullice: Fix coding standard violations: 8 according to JSON API's testing, 13 according to core's testing
Security (also included in 8.x-1.24)
- #166860 by gabesullice, Wim Leers, effulgentsia, tstoeckler, amateescu, e0ipso, hchonov, dawehner, berdir, kristiaanvandeneynde, larowlan: Improve collection filtering
- #166214 by e0ipso, dawehner, gabesullice, Wim Leers: Improved non-GET routing