In Magento 2, a REST endpoint is a PHP interface and 6 lines of XML, and the method's docblock decides what the endpoint accepts. In Laravel it's a route, a controller and a resource class, and the contract lives wherever you write it down.
Magento: a route points at an interface
webapi.xml maps a URL and an HTTP method to a method on a service contract, Magento's name for a PHP interface that a module publishes as its API. The core's own order endpoint is exactly that: GET /V1/orders/:id calls OrderRepositoryInterface::get(), and the <resource> line names the permission the caller needs. Without a token it answers 401.
<route url="/V1/orders/:id" method="GET"> <service class="Magento\Sales\Api\OrderRepositoryInterface" method="get"/> <resources> <resource ref="Magento_Sales::actions_view" /> </resources> </route> There's no controller of yours in between. Magento reads the method's docblock and builds the call from it.
/** * @param int $id The order ID. * @return \Magento\Sales\Api\Data\OrderInterface Order interface. */ // REST, SOAP and the Swagger schema all read this public function get($id); The docblock is the contract
A small test endpoint, GET /V1/acme/stock/:sku, shows how literal that is. Only its docblock changes between these 3 runs:
- Without
@return, every call fails with "Method's return type must be specified using @return annotation." - With
@param int $sku, a request forMB01is rejected before the code runs: The "MB01" value's type is invalid. The "int" type was expected. - With
@param string $skuand@return int,/rest/V1/acme/stock/MB01returns7.
The same interface also serves SOAP: the WSDL has a Qty operation with request and response types. And /rest/default/schema returns a Swagger 2.0 document with the path, a sku string parameter and an integer response. Nobody wrote that file.
So the interface is the API. Change a parameter type in a docblock and you've changed every client's contract, REST and SOAP at once.
Laravel: route, controller, resource
Laravel doesn't have that link. php artisan install:api adds routes/api.php and Sanctum. A route points at a controller, middleware checks the token, can() runs a policy, and an API Resource shapes the JSON.
Route::get('/orders/{order}', ShowOrder::class) ->middleware('auth:sanctum') ->can('view', 'order'); class ShowOrder extends Controller { public function __invoke(Order $order): OrderResource { return new OrderResource($order); } } class OrderResource extends JsonResource { public function toArray(Request $request): array { return [ 'id' => $this->id, 'status' => $this->status, 'total' => $this->grand_total, ]; } } Sent with Accept: application/json, the endpoint gives the 3 answers you'd want: 401 for a guest, 403 for another user, 200 for the owner. The body is {"data":{"id":1,"status":"processing","total":99.5}}, because Resources wrap the payload in data by default. Leave the header out and the guest gets a 500 instead: Laravel tries to redirect to a login route that an API-only app doesn't have.
One name ties the 3 pieces together: {order} in the route, Order $order in the controller and 'order' in can(). Rename the controller's parameter to $o, and the owner gets a 403. Without can() it's worse: a 200 with an empty order, {"data":{"id":null,"status":null,"total":null}}. Magento ties :sku in the URL to $sku by name too, but it fails loudly: rename the placeholder to :code, and the call gets a 400, "sku" is required.
The input side is yours too. What @param int did in Magento is a route constraint or a Form Request in Laravel, and you write it.
And nothing in the framework generates an OpenAPI schema. Packages like Scramble build one from the code, so you choose: spec first, or code first.
Where I wrote it down first
On a Laravel order system I built alone, the spec came first. The import API was an OpenAPI file before the implementation was final, and I iterated on it with the client in a Swagger editor. That's where the awkward questions came up, like split deliveries and commissions to several suppliers, while the answers were still cheap to change.
From an early version of the spec I generated a PHP client for the integration team. The import work, spec iterations included, came to about 75 of the system's 385 hours.
The rule
In Magento the contract is derived from the code. A docblock on a service contract looks like a comment, and it's a public API: REST clients, SOAP clients and the generated schema all depend on it. Review it like one. In Laravel the code doesn't produce a contract, so write one: an OpenAPI file first, then make the routes and resources match it.
Next: state vs steps, Magento's declarative schema next to Laravel's migrations.
Do you write the OpenAPI spec before the controller, or generate it from the code?
Part 6 of 15 of the Magento 2 vs Laravel series. Originally published on LinkedIn.