Skip to content

Latest commit

 

History

History
133 lines (103 loc) · 8.89 KB

README.md

File metadata and controls

133 lines (103 loc) · 8.89 KB
Raw

(Beta) MyAPI - Component

Project status - beta Latest Stable Version Total Downloads PHP Required Version MIT License Psalm Coverage Code size
PHPUnit coverage PHPUnit classes coverage PHPUnit lines coverage PHPUnit methods coverage
Phan build Psalm build PHPMd build PHPStan build PHPCodeSniffer build PHPDocumentor build Pdepend build PHPUnit build PHPUnit build GithubPages build

PHP JSON-RPC server and client with json-schema auto-generation and validation using DTO

Installation

Please wait for initial public release at sshilko/php-api-myrpc.

composer require sshilko/php-api-myrpc-beta

Compatibility

  • PHP >= 8.1

Why RPC

Over the years, first in 2007-2010 json became popular and took over the XML in the RPC space as more readable and browser/javascript friendly format. Few proposals were created to unify the request/response for the json rpc api.

Later REST took over by offering resource endpoints that fit really nice for simple CRUD apps, but it required more upfront investment into designing your APIs, and as API codebase grew and usually in monolith new functionality been added, the complexity grew fast.

REST API and JSON-RPC API comparison:

  • JSON-RPC is more loosely typed with OSI-4 Transport layer
    • REST is stricter and defines OSI-7 Application layer
  • JSON-RPC reuses only json and json-schema in contract definition
    • REST may use multiple standards like Swagger/OpenAPI, XML, JSON, HATEOAS, JSON-LD and Hydra (Hydra is an extension of JSON-LD, essentially another OpenAPI standard)
  • JSON-RPC does not say anything about caching, as it does not rely on HTTP layer
    • REST defines requirements about behaviour in caching, endpoint naming, Idempotence - in reality none of this is guaranteed by any framework, up to exact implementation by developer
  • REST api defines HTTP status codes to be used for response, which may lead to "faster" processing on client
    • in practice most of the time the error message or error trace is still dispatched in the body and will be parsed by client
    • in RPC, we do not rely on headers or cookies, error message format is documented in standard, error logging and response/transport are different concerns and should not be mixed

TLDR REST requires good knowledge in both technology and domain to design proper API, enforces strict implementation rules. GRPC requires less preparation to start with, offers typed schema validation for input and output, implementation is flexible.

in 2022 overall JSON-RPC evolved into Google gRPC

  • both are binary formats (either with HTTP1 or HTTP2 compressions) or json-rpc wrapped in MsgPack
  • both are strictly typed, with json-rpc requires manual schema validation (library concern)
  • both provide some sort of auto generated schema for clients to build API contract

JSON-RPC may not be as widespread as gRPC, but it is

  • simpler to adopt
  • works as reliable as HTTP (network guarantees), HTTP is available in any mobile/web/iot device
  • all existing HTTP tooling can be reused (initial json benefits) during development
  • one can easily adopt REST, gRPC or Swagger if already implemented JSON-RPC (rarely the case other way)
  • OpenAPI v3 Swagger is almost compatible with JSON-RPC

What is the best use-case for this library

  • Facade for the business logic
  • Simplicity focused, not a generic one-fit-all solution
  • Minimum 3rd party dependencies
  • No compilation required
  • JSON-Schema auto generation for clients

Out of scope

This library is not intending to become a framework, to keep focus and minimize codebase, it does NOT provide:

  • HTML or other easy way to navigate the API, this can be achieved with 3rd party json-schema transpilers
  • Non JSON based API, this implementation focuses on JSON representation
    • other wrapping/format is supported, please contribute your implementations
  • Authorization, authentication, security or other components required for full-fledged user-facing web-application

please re-use existing solutions that best fit your requirements.

Why this library exists

  • APIPlatform is overcomplicated and long-term commitment,
    • depends heavily on Doctrine and Symfony
    • large codebase with hidden complexity and maintainability issues
  • zendframework/zend-json-server abandoned and non-flexible
  • Simple facade for business logic with I/O validation is always needed in API-first application
  • Re-use the power of strict typed I/O with standard error messages that PHP8 provides
  • Simple, fast, easy to read and extend for your needs, easy to iterate and contribute to

Future roadmap

  • 1.0 stable release

Contributing

Authors

Sergei Shilko [email protected]