README

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

Please read contributing document

Authors

Sergei Shilko contact@sshilko.com

sshilko / php-api-myrpc-beta

Maintainers

Details