Building APIs with PHP: A Guide to REST and GraphQL

4 min readSep 23, 2024

In today’s software development landscape, APIs are critical to connecting different services, systems, and applications. PHP, one of the most widely used server-side languages, provides powerful tools to build APIs that can expose data and functionality to a variety of consumers — whether it’s mobile apps, web apps, or other backend services. In this guide, we’ll explore how to build APIs with PHP, focusing on both REST and GraphQL.

1. Understanding REST and GraphQL

Before diving into implementation, it’s essential to understand the key differences between REST and GraphQL:

REST (Representational State Transfer):

REST is an architectural style that provides a set of rules for building scalable web services. REST APIs are typically based on HTTP and CRUD operations (Create, Read, Update, Delete).
Resources are represented as URLs, and operations are performed using HTTP methods such as GET, POST, PUT, and DELETE.
Example:
GET /api/users/1 to retrieve a user with ID 1.
POST /api/users to create a new user.

GraphQL:

GraphQL is a query language for APIs developed by Facebook. It allows clients to specify exactly what data they need from the server.
Instead of multiple endpoints for different data, GraphQL has a single endpoint, and clients specify their data requirements in the query.
Example:
A single query can request a user’s details along with their associated posts.

Both REST and GraphQL have their advantages: REST is simple and well-suited for traditional CRUD operations, while GraphQL offers flexibility and efficiency when dealing with complex data requirements.

2. Setting Up PHP for API Development

To build an API in PHP, you’ll need the following tools and libraries:

PHP 7.x or PHP 8.x: Ensure your PHP version supports modern features such as typed properties and attributes.
Composer: PHP’s dependency manager to handle libraries.
Slim Framework or Laravel (for REST): These frameworks simplify API routing and structure.
GraphQL-PHP or Laravel Lighthouse (for GraphQL): Libraries to handle GraphQL queries.

Start by setting up a basic PHP project using Composer:

composer init
composer require slim/slim
composer require vlucas/phpdotenv  # For environment variables

Directory Structure:

/api-project
├── src/
│   └── Controllers/
├── public/
│   └── index.php
├── .env
├── composer.json

In public/index.php, you can initialize your application:

<?php

require '../vendor/autoload.php';

$app = new \Slim\App();

$app->get('/hello/{name}', function ($request, $response, $args) {
    $name = $args['name'];
    $response->getBody()->write("Hello, $name");
    return $response;
});

$app->run();

3. Building a RESTful API in PHP

Let’s walk through building a simple REST API for managing users.

3.1 Define Routes

For a typical REST API, you’ll need routes that map to HTTP methods:

GET /users – Get all users.
POST /users – Create a new user.
GET /users/{id} – Get a single user.
PUT /users/{id} – Update a user.
DELETE /users/{id} – Delete a user.

$app->get('/users', 'UserController:getAll');
$app->post('/users', 'UserController:create');
$app->get('/users/{id}', 'UserController:get');
$app->put('/users/{id}', 'UserController:update');
$app->delete('/users/{id}', 'UserController:delete');

3.2 Create a Controller

Controllers handle the business logic. For example, the UserController might look like this:

class UserController {

    public function getAll($request, $response) {
        $users = User::all(); // Assume User is a model interacting with the database
        return $response->withJson($users);
    }

    public function create($request, $response) {
        $data = $request->getParsedBody();
        $user = User::create($data);
        return $response->withJson($user, 201);
    }

    // Other methods for get, update, delete...
}

3.3 Working with Models

You can use an ORM like Eloquent to interact with the database:

use Illuminate\Database\Eloquent\Model;

class User extends Model {
    protected $fillable = ['name', 'email', 'password'];
}

REST is straightforward and efficient for simple CRUD operations, but for complex queries and over-fetching or under-fetching issues, GraphQL offers a more flexible solution.

4. Building a GraphQL API in PHP

To get started with GraphQL, install a GraphQL library:

composer require webonyx/graphql-php

4.1 Define a Schema

GraphQL APIs revolve around schemas that define the data types and operations.

use GraphQL\Type\Definition\Type;
use GraphQL\Type\Definition\ObjectType;
use GraphQL\Schema;

$userType = new ObjectType([
    'name' => 'User',
    'fields' => [
        'id' => Type::int(),
        'name' => Type::string(),
        'email' => Type::string(),
    ],
]);

$queryType = new ObjectType([
    'name' => 'Query',
    'fields' => [
        'user' => [
            'type' => $userType,
            'args' => ['id' => Type::int()],
            'resolve' => function($root, $args) {
                return User::find($args['id']);
            }
        ]
    ]
]);

$schema = new Schema(['query' => $queryType]);

4.2 Handling Queries

In your index.php, set up a GraphQL endpoint:

$app->post('/graphql', function ($request, $response) use ($schema) {
    $input = json_decode($request->getBody(), true);
    $query = $input['query'];

    $result = \GraphQL\GraphQL::executeQuery($schema, $query);
    return $response->withJson($result->toArray());
});

4.3 Running a Query

Clients can query the API as follows:

{
  user(id: 1) {
    name
    email
  }
}

GraphQL allows clients to request specific fields, reducing data transfer and allowing for flexible queries.

5. Securing Your API

Security is paramount when building APIs. Here are some best practices:

Authentication: Use JWT (JSON Web Token) or OAuth 2.0 for secure authentication.
Rate Limiting: Prevent abuse by limiting the number of requests a client can make.
Data Validation: Always validate incoming data to prevent injection attacks.
HTTPS: Ensure your API is served over HTTPS to encrypt data in transit.

6. Performance Optimization

Caching: Use tools like Redis or Memcached to cache frequently requested data.
Pagination: For large datasets, implement pagination to limit the amount of data returned.
Lazy Loading (GraphQL): With GraphQL, avoid over-fetching by requesting only the needed fields.

7. Conclusion

Building APIs with PHP, whether using REST or GraphQL, is a powerful way to expose functionality to different clients. REST provides simplicity and familiarity, while GraphQL offers flexibility and efficiency for complex data queries. By following best practices for security and performance, your PHP-based API can be scalable, secure, and easy to maintain.