JSON-RPC 2.0 this is a simple stateless protocol for creating an RPC (Remote Procedure Call) style API. It usually looks as follows:
You have one single endpoint on the server that accepts requests with a body of the form:
{"jsonrpc": "2.0", "method": "post.like", "params": {"post": "12345"}, "id": 1}
And it returns answers of the view:
{"jsonrpc": "2.0", "result": {"likes": 123}, "id": 1}
If an error occurs - the error response:
{"jsonrpc": "2.0", "error": {"code": 404, "message": "Post not found"}, "id": "1"}
And it's all! Did I say that is easy?
Bonus support batch operations:
Request:
[
{"jsonrpc":"2.0","method":"server.shutdown","params":{"server":"42"},"id":1},
{"jsonrpc":"2.0","method":"server.remove","params":{"server":"24"},"id":2}
]
Response:
[
{"jsonrpc":"2.0","result":{"status":"down"},"id":1}
{"jsonrpc":"2.0","error":{"code":404,"message":"Server not found"},"id": 2}
]
In the id field, the API client can send anything so that after receiving responses from the server, match them with requests.
Also, the client can send “notifications” - requests without an “id” field that do not require a response from the server:
{"jsonrpc":"2.0","method":"analytics:trackView","params":{"type": "post", "id":"123"}}
Not so long ago I became acquainted with this protocol, but it is great for my tasks of creating an API on Laravel. To use such a protocol in your application, you need to set the dependency using the composer:
$ composer require sajya/server
All actions are described in Procedure
classes, it is a familiar controller, but it must contain the static property name
.
Create the following artisan class:
php artisan make:procedure TennisProcedure
A new file will be created in the app/Http/Procedures/TennisProcedure.php
Let's call the new procedure tennis
, to do this, change the name
property and add the pong
returning value to the ping
method to get this content:
namespace App\Http\Procedures;
use Sajya\Server\Procedure;
class TennisProcedure extends Procedure
{
/**
* The name of the procedure that will be
* displayed and taken into account in the search
*/
public static string $name = 'tennis';
/**
* Execute the procedure.
*
* @return string
*/
public function ping(): string
{
return 'pong';
}
}
Like the controller, the procedure needs to be registered in the routes file, define it in the file api.php
:
use App\Http\Procedures\TennisProcedure;
Route::rpc('/v1/endpoint', [
TennisProcedure::class
])->name('rpc.endpoint');
In order to turn to the required method, you must pass the name specified in the class and the necessary method with the delimiter "@" character. In our case, it will be: tennis@ping
.
Let's make a curl
call to the new API:
curl 'http://127.0.0.1:8000/api/v1/endpoint' --data-binary '{"jsonrpc":"2.0","method":"tennis@ping","params":[],"id" : 1}'
The result will be the resulting JSON string:
{"id":"1","result":"pong","jsonrpc":"2.0"}
Top comments (0)