Goal

The end goal is to have the stability of the dynamic_page_cache and big_pipe modules, which thanks to their rigorous test coverage have seen barely any bug reports over the course of more than a year. To achieve that, we may need a level of functional test coverage similar to the REST module (as added in #2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method).

Plan

Roughly in order of sensible execution, but many things can be done in parallel.

  1. Confidence: validate all JSON API responses against the spec: #2840677: Validate responses against the JSON API specification
  2. Complexity: route handling (see details of current pain points described in #2841591: Remove EntityResource, move its logic into RequestHandler, clean up routes).
  3. Complexity: refactor away the following classes:
    1. Drupal\jsonapi\Resource\EntityCollection
    2. Drupal\jsonapi\Resource\JsonApiDocumentTopLevel
    3. Drupal\jsonapi\RequestCacheabilityDependency, issue: #2846659: Remove \Drupal\jsonapi\RequestCacheabilityDependency, use \Drupal\jsonapi\JsonApiSpec::getReservedQueryParameters() instead
  4. Confidence + complexity: simplify + add strict, comprehensive tests + add architectural documentation to the following subnamespaces in the JSON API module:
    1. src/Access, issue: #2829328: Clean up Drupal\jsonapi\Access\CustomParameterNames and make it follow the spec more closely
    2. src/Context, issue: #2842145: Add comprehensive unit test coverage for \Drupal\jsonapi\Context\FieldResolver
    3. src/Error, issue: #2829977: SerializableHttpException and Drupal\jsonapi\Error\* are not necessary
    4. src/FieldResolver
    5. src/Normalizer
    6. src/Query
    7. src/Routing/Param
  5. Complexity: remove the following subnamesapces in the JSON API module, because they should be addressed in core
    1. src/Field, blocked on: #2825487: Fix normalization of File entities & File fields: file entities should expose the file URL as a computed base field
    2. src/LinkManager, blocked on #2854830: Move rest/serialization module's "link manager" services to HAL module, issue: #2829746: Clean up \Drupal\jsonapi\LinkManager\LinkManager(Interface)
    3. src/ParamConverter, blocked on #2353611: Make it possible to link to an entity by UUID
    4. src/ResourceResponseInterface, fixed in #2857658: Get rid of ResourceResponseInterface
  6. Confidence: correctness verification + regression guards by implementing comprehensive functional tests, similar to #2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method

Comments

Wim Leers created an issue. See original summary.

Wim Leers’s picture

Issue summary: View changes

#2353611: Make it possible to link to an entity by UUID would allow JSON API to remove \Drupal\jsonapi\ParamConverter\EntityUuidConverter.

Wim Leers’s picture

dawehner’s picture

src/ResourceResponseInterface

I'm really wondering how useful is to have this interface in the first place

a) Why would anyone want to have a different implementation of that
b) This class seems to be mostly handled internally. Maybe we don't need an interface in the first place?

Wim Leers’s picture

#6++, exactly :)

e0ipso’s picture

+1 to #6.

dawehner’s picture

Issue summary: View changes
Wim Leers’s picture

Wim Leers’s picture

Title: Next steps: the path to stability for the JSON API module » [PP-2] Next steps: the path to stability for the JSON API module
Issue summary: View changes
Related issues: +#2825487: Fix normalization of File entities & File fields: file entities should expose the file URL as a computed base field

Removing src/Field is blocked on #2825487: Fix normalization of File entities & File fields: file entities should expose the file URL as a computed base field. And removing src/ParamConverter is blocked on #2353611: Make it possible to link to an entity by UUID.

That means at least two things in this Plan issue are blocked on core issues.

Wim Leers’s picture

#2829327: Review JSON API module for core-readiness is done! That means this is now the most important remaining plan issue.