DEV Community

Alexandr
Alexandr

Posted on

RPC-like API for your Laravel project

#laravel #api #jsonrpc

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}
Enter fullscreen mode Exit fullscreen mode

And it returns answers of the view:

{"jsonrpc": "2.0", "result": {"likes": 123}, "id": 1}
Enter fullscreen mode Exit fullscreen mode

If an error occurs - the error response:

{"jsonrpc": "2.0", "error": {"code": 404, "message": "Post not found"}, "id": "1"}
Enter fullscreen mode Exit fullscreen mode

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} ]
Enter fullscreen mode Exit fullscreen mode

Response:

[ {"jsonrpc":"2.0","result":{"status":"down"},"id":1} {"jsonrpc":"2.0","error":{"code":404,"message":"Server not found"},"id": 2} ]
Enter fullscreen mode Exit fullscreen mode

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"}}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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'; } }
Enter fullscreen mode Exit fullscreen mode

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');
Enter fullscreen mode Exit fullscreen mode

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}'
Enter fullscreen mode Exit fullscreen mode

The result will be the resulting JSON string:

{"id":"1","result":"pong","jsonrpc":"2.0"}
Enter fullscreen mode Exit fullscreen mode

Top comments (0)