Skip to main content

Defining and fine tuning an API in Laravel with the Stoplight Platform

Published on

Stoplight Platform is a series of tools that makes API design and documentation super easy. Their Studio product is an OpenAPI editor. Prism allows you to create a mock HTTP server to generate sample data based on your design specification. The Elements project creates documentation from your OpenAPI specification file. At Bluehorn Digital, we used Stoplight Studio to fine-tune an API provided by a Laravel (Lumen, actually) application.

I want to share how we used Stoplight Studio to customize the default Laravel model serialization API. I used Studio to create the API design and specify adjustments needed to the Laravel models (casts, date formats) and required fields in our controller request validation when creating new models. Studio also allowed us to provide documentation that could be handed off to the consumer! The consumer was also able to begin writing their integration application using the HTTP mock server provided by Prism. 💥

Note you don't need to use Stoplight's products or tools. You could use the Swagger Editor or any other OpenAPI tools. I like the Spotlight Platform the most.

This could be considered "backward," in that we didn't design the API first in an OpenAPI specification and then write the server code. However, life isn't always perfect. In our case, we had existing Laravel models and an API that we needed to expose to a new third-party consumer, where the API was entirely consumed by our own frontend. The following process allowed us to audit model data and design a proper API for third-party consumers.

The Laravel application

Let's start with a basic Laravel application and a model that will be consumed over the API.

The model, migration, factory, and controller setup

I will use a basic example using a model for a Reservation at a hotel, inn, cabin, or other.

composer create-project laravel/laravel openapi-app
cd openapi-app

Now that the Laravel application is created, we can generate a model. We will create a migration and factory. Factories allow us to create sample data for our models. We will use the factory, so we have some basic JSON schema to import into Stoplight Studio.

# Shortcut to generate a model, migration, factory, seeder, and controller...
php artisan make:model Reservation --all

Now that the model and its migration, seeder, and controller are generated, we can create its schema. This is done by editing the migration added in database/migrations. Mine was 2021_09_18_005952_create_reservations_table.php, which yours will be different due to the date!

We'll add some primary fields.

  • The reservation date (we'll pretend check-in is always at 2 PM, so the time doesn't matter.)
  • A boolean to mark if the reservation was confirmed
  • A requests and admin notes text field
  • A reference to the user who owns the reservation and who approved it.

use App\Models\User;
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateReservationsTable extends Migration
     * Run the migrations.
     * @return void
    public function up()
        Schema::create('reservations', function (Blueprint $table) {

     * Reverse the migrations.
     * @return void
    public function down()

Next, we need to edit the model so that the Eloquent ORM understands the relationships we desire on approved_by and reserved_for. Edit app/Models/Reservation.php and add the following methods so that the ORM understands our desired relationships to the User model.


namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;

class Reservation extends Model
    use HasFactory;

    public function approved_by()
        return $this->belongsTo(User::class, 'approved_by', 'id');

    public function reserved_for()
        return $this->belongsTo(User::class, 'reserved_for', 'id');


Now that we have the schema and model relationships defined, let's update the factory to generate models with sweet sample data. Edit the database/factories/ReservationFactory.php that was generated. We need to update the definition to use some random data from the Faker library. We will also randomly load a user and add it as the reference for our reservation owner and approval user.


namespace Database\Factories;

use App\Models\Reservation;
use App\Models\User;
use Illuminate\Database\Eloquent\Factories\Factory;

class ReservationFactory extends Factory
     * The name of the factory's corresponding model.
     * @var string
    protected $model = Reservation::class;

     * Define the model's default state.
     * @return array
    public function definition()
        return [
            'reservation_date' => $this->faker->iso8601(),
            'confirmed' => $this->faker->boolean(),
            'requests' => $this->faker->text(),
            'admin_notes' => $this->faker->text(),
            'approved_by' => User::inRandomOrder()->take(1)->first()->id,
            'reserved_for' => User::inRandomOrder()->take(1)->first()->id,

Then, let's update the database seeder database/seeders/DatabaseSeeder.php so we get some generated models. Note! We need to import users first since our reservation factory randomly selects user relationships.


namespace Database\Seeders;

use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
     * Seed the application's database.
     * @return void
    public function run()

For testing, we'll generate four different users and two reservations. That's more than enough to create a sample schema that we will import into Stoplight Studio for fine-tuning.

Next, we need to make a route and update the controller to retrieve our models in a serialized JSON format. Edit routes/api.php and add the following entry after the default code.

Route::get('/reservations', [App\Http\Controllers\ReservationController::class, 'index']);

Next, we need to fetch models in our ReservationController::index method. To keep things simple, we're just going to load all reservations with all relations so we can get a big picture. (Hint: we would also want an admin-based endpoint for editing and one for customers to only view.) Pop open app/Http/Controllers/ReservationController.php and give it a good ole update like the following.


namespace App\Http\Controllers;

use App\Models\Reservation;
use Illuminate\Http\Request;

class ReservationController extends Controller
     * Display a listing of the resource.
     * @return \Illuminate\Http\Response
    public function index()
        return Reservation::with('approved_by')->with('reserved_for')->get();


First. Let's get Laravel to use SQLite to avoid needing a MySQL database. Edit your .env and update the DB_* variables to:

# DB_PORT=3306
# DB_DATABASE=laravel

One more quick gotcha. Laravel will not automatically make the SQLite database file if it is missing. So create an empty file named database.sqlite in the database directory.

touch database/database.sqlite

Now that we use SQLite and have a database connection run the following to populate the database schema and sample data.

php artisan migrate --seed

Now fire up the built-in PHP server and ping that endpoint!

php artisan serve

Go to in your browser, or with cURL, and you should see some data!

JSON output from Reservations

Making an API you won't hate with Stoplight Studio

Sorry, Phil Sturgeon. I couldn't resist putting a twist on APIs You Won't Hate.

Head over to the Stoplight Studio page and get started with their online Workspace (requires an account) or download a desktop app (account optional, local storage available.) I use the desktop app connected to a workspace.

Spotlight Studio landing page



Once you have the app opened, create a new local project. I am going to call it Reservation API in this example.

Stoplight Studio landing page

Once we have our project, let's add a new API inside of the project. This is where we will begin using the user interface to generate our OpenAPI schema. Click on the API button in the sidebar to get started and give the API a name. Your API contains all of the various endpoints. If you're used to microservices architecture, each API would be its microservice.

Add new API in Stoplight Studio

Out of the box, new APIs have a default User model and paths for getting a user, adding a user, and updating a user. My first step is to delete these things usually. As far as I know, there is no way to turn this off. For this post, ignore them or go ahead and delete them.

We're going to add a new model for our reservation model in Laravel and then an endpoint that matches the path we accessed before – /api/reservations. To add new items to your project, click the blue plus button.

Stoplight Studio add dropdown

So, let's add our model! Click the add plus button, and then model. Name the model "Reservation" and set the scope to Single API, then press create. You can choose the Common option under Scope. Use this if you have APIs that the same models when designing your actual APIs.

Stoplight Studio add model popup

Now that we have a model, you will see the Generate from JSON button to create the model's schema from an existing JSON blob, which we happen to have! That's why we started the Laravel model first, so we had a baseline we could transform and improve. Click on Generate from JSON and paste the data from a Reservation model.

JSON in the Reservation model for sample data

Next, we click on Generate. And, boom! We now have a model schema that we can tweak, adjust, and verify.

Stoplight model generated schema

Okay. You might be thinking: Is this necessary? I could refresh the endpoint and keep changing my Laravel model as I specify casts, what should be hidden, etc. This is a true statement and completely valid. But. BUT. Is your API documented this way? Is there an architecture document? Are there notes? Can this be shared and mocked without an actual backend server available? At first glance, this may seem like overkill, but from my experience, it is not. We have all been on projects where we look at the code and wonder, "why in the world does this do that?!" Well, the API design document explains it all and is the contract and source of truth.

I also like this approach as it feels easier to audit the fields returned by the API and see what should be removed or restricted. For example, we do not need to know when the reference users were created, updated, had their email verified, or their email. We probably need their name field and identifier (for links.)

When you hover over a field on a model, a few icons pop up. You can move a property up or down in order, duplicate it, or delete it.

Hover shows field actions

Let's delete the created_at, updated_at, email, and email_verified_at from the approved_by and reserved_for properties.

Updated Stoplight Studio reservation model

Now that we've removed frivolous fields let's review what is left. Notice that everything is a string. The next step is to identify the different schemas for each property correctly.

  • created_at, updated_at: it's a string, but it's a date and time string
  • reservation_date: it's a string, but it's only a date (remember, we decided check-in is always at 2 PM, we don't care about the time.)
  • confirmed: this is not a string; it's a boolean! But, that's because all values are treated as strings when retrieved from the database.

First, let's address the format of the date strings. This can be done by specifying properties on these fields. We can open the properties for each field and specify the format. The row icon on the right is for Other properties.

Other properties button

Clicking that icon will open a dialog that lets us specify a format for our string fields. The OpenAPI specification has many string field types available.

Modifying a string field's format

To change a field's schema, you click on the current schema type to open a dialog. Make sure you unselect the current schema type! OpenAPI allows for unions – string OR number. So a field can be of multiple types.

Change the field schema


Woo! We've done it! We triaged our model's schema!

Next, we need to create an endpoint in Stoplight that represents the Laravel route we have already defined. Click the add plus button, and then Endpoint. Set the path to /api/reservation, just like we have it in Laravel. Click on GET to toggle the HTTP method. We are only going to define one HTTP method which allows fetching the data. Press Create to add the endpoint.

Adding an endpoint in Stoplight

With the endpoint created, we need to specify the response. Click + Response to allow specifying a response for the endpoint. This will create a default HTTP 200 response. Click on + Add Body for the response, which will enable us to specify that it returns an array of Reservation models.

Add a body to the API endpoint response


The default body response is a single object. Our endpoint currently returns an array of models. Click on object to change the schema to array. When an array is chosen, we can specify a subtype. Choose $ref for the subtype so that we can reference our Reservation model.

Specifying array of Reservation models

And we have now defined our endpoint! We can mock the response and see if we're satisfied before updating our Laravel model.

Previewing our data using Prism

The Prism HTTP server mocking tool is built into Stoplight Studio. All we have to do is click Mocks and then the API endpoint we want to mock, and we'll get the output of sample data!

Accessing our mocks

You'll notice when accessing the mocks that we could do more fine-tuning of our API specification. That's a bit outside the scope of this post. But, it shows why this step is essential! For example, we know that identifiers will not be floats or negative. These are properties that can be set on each model field. I know this may seem trivial, but will it seem trivial to a third-party consumer?

Mocked model output

Let's say this is "good enough," and we want to update our Laravel model to reflect the API we have designed.

Wrangling our Laravel model

There are two things we need to do

  • Update the castings for confirmed and reservation_date
  • Update the with method calls to restrict the returned fields from user references.

Specifying casts in our Laravel model

Models in Laravel extend Illuminate\Database\Eloquent\Model, which implements the Illuminate\Database\Eloquent\Concerns\HasAttributes trait. This trait allows us to identify how fields on our model should be cast when accessed or serialized. Using the $casts property, we can specify the cast types.

The following $casts property should be added to your Reservation model to match the API design we created in Stoplight Studio.

    protected $casts = [
        'confirmed' => 'boolean',
        'reservation_date' => 'date:Y-m-d ',

With these added, we can refresh the output from Laravel and see that the confirmed and reservation_date now meet our API design expectations! Woo 🥳

Updated reservation output with casts

Controlling the data returned from relationships

The final step is to update the user model relationships we include. We can do that by restricting the fields returned in our with calls to load relationships. We need to use a colon after the relationship name and specify the fields we want to be returned.

     * Display a listing of the resource.
     * @return \Illuminate\Http\Response
    public function index()
        return Reservation::with('approved_by:id,name')

Adding :id,name ensures only these fields are returned. And, with that change, we now meet our API design specification!

Final Laravel output


Hopefully you found this interesting! I didn't have time to research existing tooling. The Laravel community has some amazing packages out there, so many there is an OpenAPI and Eloquent ORM model package? If not, I plan on writing one!

If you need assistance with your API driven Laravel or Drupal application, contact Bluehorn Digital at [email protected] and see how my team and myself can assist you!