Dog Tower API Documentation

Comprehensive guide on creating endpoints for the Dog Tower App.

Introduction

This documentation explains how to create an endpoint that acts as a bridge between the Dog Tower App and your organization's platform. This guide covers the structure of data responses, handling edit and delete requests, and the use of actions.

Data Response Structure

All API responses should be in JSON format. The response structure should include relevant data fields such as id, name, notes, status, and any other necessary fields. Additionally, it should include metadata such as styles and permissions.

Example response structure:

{
  "id": "unique-id",
  "name": "Sample Name",
  "notes": "Sample Notes",
  "status": "Pending",
  "styles": {
    "id": {
      "font": "AppleSystemUIFont",
      "fontSize": 12,
      "color": "#FFFFFF"
    },
    "name": {
      "font": "AppleSystemUIFont",
      "fontSize": 16,
      "color": "#FFFFFF"
    },
    "notes": {
      "font": "AppleSystemUIFont",
      "fontSize": 14,
      "color": "#FFFFFF"
    },
    "status": {
      "font": "AppleSystemUIFont",
      "fontSize": 14,
      "color": "#00FF00"
    }
  },
  "permissions": {
    "canEdit": true,
    "canDelete": true
  }
}

Handling Edit Requests

Edit requests are sent to the server using the PUT method. The request will include the id of the record to be updated along with the updated data fields. The server should validate the incoming data and update the corresponding record in the storage.

The response to a successful edit request should include the updated record data. If the record is not found, the server should respond with a 404 error.

Handling Delete Requests

Delete requests are sent to the server using the DELETE method. The request will include the id of the record to be deleted. The server should locate the record and remove it from the storage.

The response to a successful delete request should confirm the deletion. If the record is not found, the server should respond with a 404 error.

Using Actions

Actions in the Dog Tower App allow users to perform specific operations like creating, updating, or deleting records. These actions correspond to the standard HTTP methods: GET, POST, PUT, and DELETE.

Ensure that your endpoint correctly handles these HTTP methods and responds with appropriate status codes and data structures. Actions should be designed to be idempotent, meaning repeated requests should have the same effect as a single request.

Create an Endpoint

To create an endpoint for the Dog Tower App, follow the PHP example below. This example demonstrates how to handle GET, POST, PUT, and DELETE requests, manage JSON data, and format API responses.

<?php

header('Content-Type: application/json');

$file = 'data.json';

if (!file_exists($file)) {
    file_put_contents($file, json_encode([]));
}

$data = json_decode(file_get_contents($file), true);

$requestMethod = $_SERVER['REQUEST_METHOD'];

switch ($requestMethod) {
    case 'GET':
        if (isset($_GET['id'])) {
            $id = $_GET['id'];
            $record = getRecordById($id, $data);
            if ($record) {
                response(200, $record);
            } else {
                response(404, ["message" => "Record not found"]);
            }
        } else {
            response(200, $data);
        }
        break;

    case 'POST':
        $input = json_decode(file_get_contents('php://input'), true);
        $input = array_merge($input, $_GET);

        if (isset($input['name'], $input['notes'], $input['status'])) {
            $newRecord = [
                'id' => uniqid(),
                'name' => $input['name'],
                'notes' => $input['notes'],
                'status' => $input['status'],
                'styles' => [
                    'id' => [
                        'font' => 'AppleSystemUIFont',
                        'fontSize' => 12,
                        'color' => '#FFFFFF'
                    ],
                    'name' => [
                        'font' => 'AppleSystemUIFont',
                        'fontSize' => 16,
                        'color' => '#FFFFFF'
                    ],
                    'notes' => [
                        'font' => 'AppleSystemUIFont',
                        'fontSize' => 14,
                        'color' => '#FFFFFF'
                    ],
                    'status' => [
                        'font' => 'AppleSystemUIFont',
                        'fontSize' => 14,
                        'color' => '#00FF00'
                    ]
                ],
                'dogTowerSettings' => [
                    'permissions' => [
                        'canEdit' => true,
                        'canDelete' => true
                    ]
                ]
            ];
            $data[] = $newRecord;
            file_put_contents($file, json_encode($data));
            response(201, $newRecord);
        } else {
            response(400, ["message" => "Invalid input"]);
        }
        break;

    case 'PUT':
        $input = json_decode(file_get_contents('php://input'), true);
        if (isset($input['id'], $input['name'], $input['notes'], $input['status'])) {
            $index = getRecordIndexById($input['id'], $data);
            if ($index !== false) {
                $existingRecord = $data[$index];
                $data[$index] = [
                    'id' => $input['id'],
                    'name' => $input['name'],
                    'notes' => $input['notes'],
                    'status' => $input['status'],
                    'styles' => $existingRecord['styles'],
                    'dogTowerSettings' => $existingRecord['dogTowerSettings']
                ];
                file_put_contents($file, json_encode($data));
                response(200, $data[$index]);
            } else {
                response(404, ["message" => "Record not found"]);
            }
        } else {
            response(400, ["message" => "Invalid input"]);
        }
        break;

    case 'DELETE':
        if (isset($_GET['id'])) {
            $id = $_GET['id'];
            $index = getRecordIndexById($id, $data);
            if ($index !== false) {
                array_splice($data, $index, 1);
                file_put_contents($file, json_encode($data));
                response(200, ["message" => "Record deleted"]);
            } else {
                response(404, ["message" => "Record not found"]);
            }
        } else {
            response(400, ["message" => "Invalid input"]);
        }
        break;

    default:
        response(405, ["message" => "Method Not Allowed"]);
        break;
}

function response($status, $data) {
    http_response_code($status);
    echo json_encode($data);
    exit();
}

function getRecordById($id, $data) {
    foreach ($data as $record) {
        if ($record['id'] === $id) {
            return $record;
        }
    }
    return false;
}

function getRecordIndexById($id, $data) {
    foreach ($data as $index => $record) {
        if ($record['id'] === $id) {
            return $index;
        }
    }
    return false;
}

?>

Handling GET Requests

To retrieve all records or a specific record by ID, handle GET requests as shown in the example above.

GET /api/records: Retrieve all records.
GET /api/records/{id}: Retrieve a specific record by ID.

Handling POST Requests

To create a new record, handle POST requests as shown in the example above.

{
  "name": "Demo One",
  "notes": "Demo",
  "status": "Open"
}

Handling PUT Requests

To update an existing record, handle PUT requests as shown in the example above.

{
  "id": "6684afd42eaf4",
  "name": "Demo One Updated",
  "notes": "Updated Notes",
  "status": "Closed"
}

Handling DELETE Requests

To delete a record, handle DELETE requests as shown in the example above.

{
  "id": "6684afd42eaf4"
}