add: more sharing groups api tests, add broods api tests, extend openapi spec

tests/Fixture/BroodsFixture.php

@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Test\Fixture;
+
+use Cake\TestSuite\Fixture\TestFixture;
+
+class BroodsFixture extends TestFixture
+{
+    public $connection = 'test';
+
+    public const BROOD_A_ID = 1;
+    public const BROOD_A_API_KEY = '6dcd4ce23d88e2ee9568ba546c007c63d9131c1b';
+
+    public const BROOD_B_ID = 2;
+    public const BROOD_B_API_KEY = 'ae4f281df5a5d0ff3cad6371f76d5c29b6d953ec';
+
+    public function init(): void
+    {
+        $faker = \Faker\Factory::create();
+
+        $this->records = [
+            [
+                'id' => self::BROOD_A_ID,
+                'uuid' => $faker->uuid(),
+                'name' => 'Brood A',
+                'url' => $faker->url,
+                'description' => $faker->text,
+                'organisation_id' => OrganisationsFixture::ORGANISATION_A_ID,
+                'trusted' => true,
+                'pull' => true,
+                'skip_proxy' => true,
+                'authkey' => self::BROOD_A_API_KEY,
+                'created' => $faker->dateTime()->getTimestamp(),
+                'modified' => $faker->dateTime()->getTimestamp()
+            ],
+            [
+                'id' => self::BROOD_B_ID,
+                'uuid' => $faker->uuid(),
+                'name' => 'Brood A',
+                'url' => $faker->url,
+                'description' => $faker->text,
+                'organisation_id' => OrganisationsFixture::ORGANISATION_B_ID,
+                'trusted' => true,
+                'pull' => true,
+                'skip_proxy' => true,
+                'authkey' => self::BROOD_B_API_KEY,
+                'created' => $faker->dateTime()->getTimestamp(),
+                'modified' => $faker->dateTime()->getTimestamp()
+            ]
+        ];
+        parent::init();
+    }
+}

tests/Fixture/OrganisationsFixture.php

@@ -5,7 +5,6 @@ declare(strict_types=1);
 namespace App\Test\Fixture;
 
 use Cake\TestSuite\Fixture\TestFixture;
-use Authentication\PasswordHasher\DefaultPasswordHasher;
 
 class OrganisationsFixture extends TestFixture
 {

tests/Fixture/SharingGroupsFixture.php

@@ -22,7 +22,7 @@ class SharingGroupsFixture extends TestFixture
                 'id' => self::SHARING_GROUP_A_ID,
                 'uuid' => $faker->uuid(),
                 'name' => 'Sharing Group A',
-                'releasability' => 'Sharing Group A',
+                'releasability' => 'Sharing Group A releasability',
                 'description' => 'Sharing Group A description',
                 'organisation_id' => OrganisationsFixture::ORGANISATION_A_ID,
                 'user_id' => UsersFixture::USER_ADMIN_ID,
@@ -35,7 +35,7 @@ class SharingGroupsFixture extends TestFixture
                 'id' => self::SHARING_GROUP_B_ID,
                 'uuid' => $faker->uuid(),
                 'name' => 'Sharing Group B',
-                'releasability' => 'Sharing Group B',
+                'releasability' => 'Sharing Group B releasability',
                 'description' => 'Sharing Group B description',
                 'organisation_id' => OrganisationsFixture::ORGANISATION_B_ID,
                 'user_id' => UsersFixture::USER_ADMIN_ID,

tests/TestCase/Api/Broods/AddBroodApiTest.php

@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Test\TestCase\Api\Users;
+
+use Cake\TestSuite\IntegrationTestTrait;
+use Cake\TestSuite\TestCase;
+use App\Test\Fixture\OrganisationsFixture;
+use App\Test\Fixture\AuthKeysFixture;
+use App\Test\Helper\ApiTestTrait;
+
+class AddBroodApiTest extends TestCase
+{
+    use IntegrationTestTrait;
+    use ApiTestTrait;
+
+    protected const ENDPOINT = '/api/v1/broods/add';
+
+    protected $fixtures = [
+        'app.Organisations',
+        'app.Individuals',
+        'app.Roles',
+        'app.Users',
+        'app.AuthKeys',
+        'app.Broods'
+    ];
+
+    public function setUp(): void
+    {
+        parent::setUp();
+        $this->initializeValidator(APP . '../webroot/docs/openapi.yaml');
+    }
+
+    public function testAddBrood(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::ADMIN_API_KEY);
+
+        $faker = \Faker\Factory::create();
+        $uuid = $faker->uuid;
+
+        $this->post(
+            self::ENDPOINT,
+            [
+                'uuid' => $uuid,
+                'name' => 'Brood A',
+                'url' => $faker->url,
+                'description' => $faker->text,
+                'organisation_id' => OrganisationsFixture::ORGANISATION_A_ID,
+                'trusted' => true,
+                'pull' => true,
+                'skip_proxy' => true,
+                'authkey' => $faker->sha1,
+            ]
+        );
+
+        $this->assertResponseOk();
+        $this->assertResponseContains(sprintf('"uuid": "%s"', $uuid));
+        $this->assertDbRecordExists('Broods', ['uuid' => $uuid]);
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec(self::ENDPOINT, 'post');
+    }
+
+    public function testAddBroodNotAllowedAsRegularUser(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::REGULAR_USER_API_KEY);
+
+        $faker = \Faker\Factory::create();
+        $uuid = $faker->uuid;
+
+        $this->post(
+            self::ENDPOINT,
+            [
+                'uuid' => $uuid,
+                'name' => 'Brood A',
+                'url' => $faker->url,
+                'description' => $faker->text,
+                'organisation_id' => OrganisationsFixture::ORGANISATION_A_ID,
+                'trusted' => true,
+                'pull' => true,
+                'skip_proxy' => true,
+                'authkey' => $faker->sha1,
+            ]
+        );
+
+        $this->assertResponseCode(405);
+        $this->assertDbRecordNotExists('Broods', ['uuid' => $uuid]);
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec(self::ENDPOINT, 'post');
+    }
+}

tests/TestCase/Api/Broods/DeleteBroodsApiTest.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Test\TestCase\Api\Users;
+
+use Cake\TestSuite\IntegrationTestTrait;
+use Cake\TestSuite\TestCase;
+use App\Test\Fixture\AuthKeysFixture;
+use App\Test\Fixture\BroodsFixture;
+use App\Test\Helper\ApiTestTrait;
+
+class DeleteBroodsApiTest extends TestCase
+{
+    use IntegrationTestTrait;
+    use ApiTestTrait;
+
+    protected const ENDPOINT = '/api/v1/broods/delete';
+
+    protected $fixtures = [
+        'app.Organisations',
+        'app.Individuals',
+        'app.Roles',
+        'app.Users',
+        'app.AuthKeys',
+        'app.Broods'
+    ];
+
+    public function setUp(): void
+    {
+        parent::setUp();
+        $this->initializeValidator(APP . '../webroot/docs/openapi.yaml');
+    }
+
+    public function testDeleteBrood(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::ADMIN_API_KEY);
+        $url = sprintf('%s/%d', self::ENDPOINT, BroodsFixture::BROOD_A_ID);
+        $this->delete($url);
+
+        $this->assertResponseOk();
+        $this->assertDbRecordNotExists('Broods', ['id' => BroodsFixture::BROOD_A_ID]);
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec($url, 'delete');
+        $this->addWarning('TODO: CRUDComponent::delete() sets some view variables, does not take into account `isRest()`, fix it.');
+    }
+
+    public function testDeleteBroodNotAllowedAsRegularUser(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::REGULAR_USER_API_KEY);
+        $url = sprintf('%s/%d', self::ENDPOINT, BroodsFixture::BROOD_A_ID);
+        $this->delete($url);
+
+        $this->assertResponseCode(405);
+        $this->assertDbRecordExists('Broods', ['id' => BroodsFixture::BROOD_A_ID]);
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec($url, 'delete');
+        $this->addWarning('TODO: CRUDComponent::delete() sets some view variables, does not take into account `isRest()`, fix it.');
+    }
+}

tests/TestCase/Api/Broods/EditBroodApiTest.php

@@ -0,0 +1,83 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Test\TestCase\Api\Users;
+
+use Cake\TestSuite\IntegrationTestTrait;
+use Cake\TestSuite\TestCase;
+use App\Test\Fixture\AuthKeysFixture;
+use App\Test\Fixture\OrganisationsFixture;
+use App\Test\Fixture\BroodsFixture;
+use App\Test\Helper\ApiTestTrait;
+
+class EditBroodApiTest extends TestCase
+{
+    use IntegrationTestTrait;
+    use ApiTestTrait;
+
+    protected const ENDPOINT = '/api/v1/broods/edit';
+
+    protected $fixtures = [
+        'app.Organisations',
+        'app.Individuals',
+        'app.Roles',
+        'app.Users',
+        'app.AuthKeys',
+        'app.Broods'
+    ];
+
+    public function setUp(): void
+    {
+        parent::setUp();
+        $this->initializeValidator(APP . '../webroot/docs/openapi.yaml');
+    }
+
+    public function testEditBrood(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::ADMIN_API_KEY);
+
+        $url = sprintf('%s/%d', self::ENDPOINT, BroodsFixture::BROOD_A_ID);
+        $this->put(
+            $url,
+            [
+                'name' => 'Test Brood 4321',
+            ]
+        );
+
+        $this->assertResponseOk();
+        $this->assertDbRecordExists(
+            'Broods',
+            [
+                'id' => BroodsFixture::BROOD_A_ID,
+                'name' => 'Test Brood 4321',
+            ]
+        );
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec($url, 'put');
+    }
+
+    public function testEditBroodNotAllowedAsRegularUser(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::REGULAR_USER_API_KEY);
+
+        $url = sprintf('%s/%d', self::ENDPOINT, BroodsFixture::BROOD_B_ID);
+        $this->put(
+            $url,
+            [
+                'name' => 'Test Brood 1234'
+            ]
+        );
+
+        $this->assertResponseCode(405);
+        $this->assertDbRecordNotExists(
+            'Broods',
+            [
+                'id' => BroodsFixture::BROOD_B_ID,
+                'name' => 'Test Brood 1234'
+            ]
+        );
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec($url, 'put');
+    }
+}

tests/TestCase/Api/Broods/IndexBroodsApiTest.php

@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Test\TestCase\Api\Users;
+
+use Cake\TestSuite\IntegrationTestTrait;
+use Cake\TestSuite\TestCase;
+use App\Test\Fixture\AuthKeysFixture;
+use App\Test\Fixture\BroodsFixture;
+use App\Test\Helper\ApiTestTrait;
+
+class IndexBroodsApiTest extends TestCase
+{
+    use IntegrationTestTrait;
+    use ApiTestTrait;
+
+    protected const ENDPOINT = '/api/v1/users/index';
+
+    protected $fixtures = [
+        'app.Organisations',
+        'app.Individuals',
+        'app.Roles',
+        'app.Users',
+        'app.AuthKeys',
+        'app.Broods'
+    ];
+
+    public function setUp(): void
+    {
+        parent::setUp();
+        $this->initializeValidator(APP . '../webroot/docs/openapi.yaml');
+    }
+
+    public function testIndexBroods(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::ADMIN_API_KEY);
+        $this->get(self::ENDPOINT);
+
+        $this->assertResponseOk();
+        $this->assertResponseContains(sprintf('"id": %d', BroodsFixture::BROOD_A_ID));
+        // TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec(self::ENDPOINT);
+    }
+}

tests/TestCase/Api/Broods/ViewBroodApiTest.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Test\TestCase\Api\Users;
+
+use Cake\TestSuite\IntegrationTestTrait;
+use Cake\TestSuite\TestCase;
+use App\Test\Fixture\AuthKeysFixture;
+use App\Test\Fixture\BroodsFixture;
+use App\Test\Helper\ApiTestTrait;
+
+class ViewBroodApiTest extends TestCase
+{
+    use IntegrationTestTrait;
+    use ApiTestTrait;
+
+    protected const ENDPOINT = '/api/v1/broods/view';
+
+    protected $fixtures = [
+        'app.Organisations',
+        'app.Individuals',
+        'app.Roles',
+        'app.Users',
+        'app.AuthKeys',
+        'app.Broods'
+    ];
+
+    public function setUp(): void
+    {
+        parent::setUp();
+        $this->initializeValidator(APP . '../webroot/docs/openapi.yaml');
+    }
+
+    public function testViewBroodGroupById(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::ADMIN_API_KEY);
+        $url = sprintf('%s/%d', self::ENDPOINT, BroodsFixture::BROOD_A_ID);
+        $this->get($url);
+
+        $this->assertResponseOk();
+        $this->assertResponseContains(sprintf('"id": %d', BroodsFixture::BROOD_A_ID));
+        // TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec($url);
+    }
+}

tests/TestCase/Api/SharingGroups/AddSharingGroupApiTest.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Test\TestCase\Api\Users;
+
+use Cake\TestSuite\IntegrationTestTrait;
+use Cake\TestSuite\TestCase;
+use App\Test\Fixture\OrganisationsFixture;
+use App\Test\Fixture\UsersFixture;
+use App\Test\Fixture\AuthKeysFixture;
+use App\Test\Helper\ApiTestTrait;
+
+class AddSharingGroupApiTest extends TestCase
+{
+    use IntegrationTestTrait;
+    use ApiTestTrait;
+
+    protected const ENDPOINT = '/api/v1/sharingGroups/add';
+
+    protected $fixtures = [
+        'app.Organisations',
+        'app.Individuals',
+        'app.Roles',
+        'app.Users',
+        'app.AuthKeys',
+        'app.SharingGroups'
+    ];
+
+    public function setUp(): void
+    {
+        parent::setUp();
+        $this->initializeValidator(APP . '../webroot/docs/openapi.yaml');
+    }
+
+    public function testAddSharingGroup(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::ADMIN_API_KEY);
+
+        $faker = \Faker\Factory::create();
+        $uuid = $faker->uuid;
+
+        $this->post(
+            self::ENDPOINT,
+            [
+                'uuid' => $uuid,
+                'name' => 'Test Sharing Group',
+                'releasability' => 'Test Sharing Group releasability',
+                'description' => 'Test Sharing Group description',
+                'organisation_id' => OrganisationsFixture::ORGANISATION_A_ID,
+                'user_id' => UsersFixture::USER_ADMIN_ID,
+                'active' => true,
+                'local' => true
+            ]
+        );
+
+        $this->assertResponseOk();
+        $this->assertResponseContains(sprintf('"uuid": "%s"', $uuid));
+        $this->assertDbRecordExists('SharingGroups', ['uuid' => $uuid]);
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec(self::ENDPOINT, 'post');
+    }
+
+    public function testAddSharingGroupNotAllowedAsRegularUser(): void
+    {
+        $this->setAuthToken(AuthKeysFixture::REGULAR_USER_API_KEY);
+
+        $faker = \Faker\Factory::create();
+        $uuid = $faker->uuid;
+
+        $this->post(
+            self::ENDPOINT,
+            [
+                'uuid' => $uuid,
+                'name' => 'Test Sharing Group',
+                'releasability' => 'Sharing Group A',
+                'description' => 'Sharing Group A description',
+                'organisation_id' => OrganisationsFixture::ORGANISATION_A_ID,
+                'user_id' => UsersFixture::USER_ADMIN_ID,
+                'active' => true,
+                'local' => true
+            ]
+        );
+
+        $this->assertResponseCode(405);
+        $this->assertDbRecordNotExists('SharingGroups', ['uuid' => $uuid]);
+        //TODO: $this->assertRequestMatchesOpenApiSpec();
+        $this->assertResponseMatchesOpenApiSpec(self::ENDPOINT, 'post');
+    }
+}

tests/TestCase/Api/SharingGroups/ViewSharingGroupApiTest.php

@@ -32,14 +32,14 @@ class ViewSharingGroupApiTest extends TestCase
         $this->initializeValidator(APP . '../webroot/docs/openapi.yaml');
     }
 
-    public function testVieSharingGroupById(): void
+    public function testViewSharingGroupById(): void
     {
         $this->setAuthToken(AuthKeysFixture::ADMIN_API_KEY);
         $url = sprintf('%s/%d', self::ENDPOINT, SharingGroupsFixture::SHARING_GROUP_A_ID);
         $this->get($url);
 
         $this->assertResponseOk();
-        $this->assertResponseContains('"name": "Sharing Group A"');
+        $this->assertResponseContains(sprintf('"id": %d', SharingGroupsFixture::SHARING_GROUP_A_ID));
         // TODO: $this->assertRequestMatchesOpenApiSpec();
         $this->assertResponseMatchesOpenApiSpec($url);
     }

tests/bootstrap.php

@@ -56,6 +56,7 @@ session_id('cli');
 
 // hacky way to skip migrations
 if (!in_array('skip-migrations', $_SERVER['argv'])) {
+    echo "[ * ] Running DB migrations, it may take some time ...\n";
     $migrator = new Migrator();
     $migrator->runMany([
         ['connection' => 'test'],
@@ -63,5 +64,5 @@ if (!in_array('skip-migrations', $_SERVER['argv'])) {
         ['plugin' => 'ADmad/SocialAuth', 'connection' => 'test']
     ]);
 } else {
-    echo "[ * ] Skipping migrations ...\n";
+    echo "[ * ] Skipping DB migrations ...\n";
 }

webroot/docs/openapi.yaml

@@ -21,6 +21,8 @@ tags:
     description: "Inbox messages represent A list of requests to be manually processed."
   - name: SharingGroups
     description: "Sharing groups are distribution lists usable by tools that can exchange information with a list of trusted partners. Create recurring or ad hoc sharing groups and share them with the members of the sharing group."
+  - name: Broods
+    description: "Cerebrate can connect to other Cerebrate instances to exchange trust information and to instrument interconnectivity between connected local tools. Each such Cerebrate instance with its connected tools is considered to be a brood."
 
 paths:
   /api/v1/individuals/index:
@@ -66,7 +68,7 @@ paths:
       tags:
         - Users
       requestBody:
-        $ref: "#/components/requestBodies/AddIndividualRequest"
+        $ref: "#/components/requestBodies/CreateIndividualRequest"
       responses:
         "200":
           $ref: "#/components/responses/IndividualResponse"
@@ -174,7 +176,7 @@ paths:
       tags:
         - Users
       requestBody:
-        $ref: "#/components/requestBodies/AddUserRequest"
+        $ref: "#/components/requestBodies/CreateUserRequest"
       responses:
         "200":
           $ref: "#/components/responses/UserResponse"
@@ -248,7 +250,7 @@ paths:
       tags:
         - Organisations
       requestBody:
-        $ref: "#/components/requestBodies/AddOrganisationRequest"
+        $ref: "#/components/requestBodies/CreateOrganisationRequest"
       responses:
         "200":
           $ref: "#/components/responses/OrganisationResponse"
@@ -445,6 +447,24 @@ paths:
         default:
           $ref: "#/components/responses/ApiErrorResponse"
 
+  /api/v1/sharingGroups/add:
+    post:
+      summary: "Add sharing group"
+      operationId: addSharingGroup
+      tags:
+        - SharingGroups
+      requestBody:
+        $ref: "#/components/requestBodies/CreateSharingGroupRequest"
+      responses:
+        "200":
+          $ref: "#/components/responses/IndividualResponse"
+        "403":
+          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
+        "405":
+          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
+        default:
+          $ref: "#/components/responses/ApiErrorResponse"
+
   /api/v1/sharingGroups/view/{sharingGroupId}:
     get:
       summary: "Get sharing group by ID"
@@ -501,6 +521,98 @@ paths:
         default:
           $ref: "#/components/responses/ApiErrorResponse"
 
+  /api/v1/broods/index:
+    get:
+      summary: "Get broods list"
+      operationId: getBroods
+      tags:
+        - Broods
+      parameters:
+        - $ref: "#/components/parameters/quickFilter"
+      responses:
+        "200":
+          $ref: "#/components/responses/BroodListResponse"
+        "403":
+          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
+        "405":
+          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
+        default:
+          $ref: "#/components/responses/ApiErrorResponse"
+
+  /api/v1/broods/view/{broodId}:
+    get:
+      summary: "Get brood by ID"
+      operationId: getBroodById
+      tags:
+        - Broods
+      parameters:
+        - $ref: "#/components/parameters/broodId"
+      responses:
+        "200":
+          $ref: "#/components/responses/BroodResponse"
+        "403":
+          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
+        "405":
+          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
+        default:
+          $ref: "#/components/responses/ApiErrorResponse"
+
+  /api/v1/broods/add:
+    post:
+      summary: "Add brood"
+      operationId: addBrood
+      tags:
+        - Broods
+      requestBody:
+        $ref: "#/components/requestBodies/CreateBroodRequest"
+      responses:
+        "200":
+          $ref: "#/components/responses/BroodResponse"
+        "403":
+          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
+        "405":
+          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
+        default:
+          $ref: "#/components/responses/ApiErrorResponse"
+
+  /api/v1/broods/edit/{sharingGroupId}:
+    put:
+      summary: "Edit brood"
+      operationId: editBrood
+      tags:
+        - Broods
+      parameters:
+        - $ref: "#/components/parameters/broodId"
+      requestBody:
+        $ref: "#/components/requestBodies/EditBroodRequest"
+      responses:
+        "200":
+          $ref: "#/components/responses/BroodResponse"
+        "403":
+          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
+        "405":
+          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
+        default:
+          $ref: "#/components/responses/ApiErrorResponse"
+
+  /api/v1/broods/delete/{broodId}:
+    delete:
+      summary: "Delete brood by ID"
+      operationId: deleteBroodById
+      tags:
+        - Broods
+      parameters:
+        - $ref: "#/components/parameters/broodId"
+      responses:
+        "200":
+          $ref: "#/components/responses/BroodResponse"
+        "403":
+          $ref: "#/components/responses/UnauthorizedApiErrorResponse"
+        "405":
+          $ref: "#/components/responses/MethodNotAllowedApiErrorResponse"
+        default:
+          $ref: "#/components/responses/ApiErrorResponse"
+
 components:
   schemas:
     # General
@@ -525,6 +637,9 @@ components:
       format: email
       example: "user@example.com"
 
+    AuthKey:
+      type: string
+
     # Individuals
     IndividualFirstName:
       type: string
@@ -906,6 +1021,59 @@ components:
       items:
         $ref: "#/components/schemas/SharingGroup"
 
+    # Broods
+    BroodName:
+      type: string
+
+    BroodDescription:
+      type: string
+
+    BroodUrl:
+      type: string
+
+    BroodIsTrusted:
+      type: boolean
+      description: "Trusted upstream source"
+
+    BroodIsPull:
+      type: boolean
+      description: "Enable pulling of trust information"
+
+    Brood:
+      type: object
+      properties:
+        id:
+          $ref: "#/components/schemas/ID"
+        uuid:
+          $ref: "#/components/schemas/UUID"
+        name:
+          $ref: "#/components/schemas/BroodName"
+        url:
+          $ref: "#/components/schemas/BroodUrl"
+        description:
+          $ref: "#/components/schemas/BroodDescription"
+        organisation_id:
+          $ref: "#/components/schemas/ID"
+        trusted:
+          $ref: "#/components/schemas/BroodIsTrusted"
+        pull:
+          $ref: "#/components/schemas/BroodIsPull"
+        skip_proxy:
+          type: boolean
+        authkey:
+          $ref: "#/components/schemas/AuthKey"
+        created:
+          $ref: "#/components/schemas/DateTime"
+        modified:
+          $ref: "#/components/schemas/DateTime"
+        organisation:
+          $ref: "#/components/schemas/Organisation"
+
+    BroodList:
+      type: array
+      items:
+        $ref: "#/components/schemas/Brood"
+
     # Errors
     ApiError:
       type: object
@@ -1007,6 +1175,14 @@ components:
       schema:
         $ref: "#/components/schemas/ID"
 
+    broodId:
+      name: broodId
+      in: path
+      description: "Numeric ID of the Brood"
+      required: true
+      schema:
+        $ref: "#/components/schemas/ID"
+
     quickFilter:
       name: quickFilter
       in: query
@@ -1027,7 +1203,7 @@ components:
 
   requestBodies:
     # Individuals
-    AddIndividualRequest:
+    CreateIndividualRequest:
       required: true
       content:
         application/json:
@@ -1064,7 +1240,7 @@ components:
                 $ref: "#/components/schemas/IndividualPosition"
 
     # Users
-    AddUserRequest:
+    CreateUserRequest:
       required: true
       content:
         application/json:
@@ -1107,7 +1283,7 @@ components:
                 type: string
 
     # Organisations
-    AddOrganisationRequest:
+    CreateOrganisationRequest:
       required: true
       content:
         application/json:
@@ -1190,6 +1366,30 @@ components:
                 type: string
 
     # SharingGroups
+    CreateSharingGroupRequest:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              uuid:
+                $ref: "#/components/schemas/UUID"
+              name:
+                $ref: "#/components/schemas/SharingGroupName"
+              releasability:
+                $ref: "#/components/schemas/SharingGroupReleasability"
+              description:
+                $ref: "#/components/schemas/SharingGroupDescription"
+              organisation_id:
+                $ref: "#/components/schemas/ID"
+              user_id:
+                $ref: "#/components/schemas/ID"
+              active:
+                type: boolean
+              local:
+                type: boolean
+
     EditSharingGroupRequest:
       required: true
       content:
@@ -1214,6 +1414,59 @@ components:
               local:
                 type: boolean
 
+    # Broods
+    CreateBroodRequest:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              uuid:
+                $ref: "#/components/schemas/UUID"
+              name:
+                $ref: "#/components/schemas/BroodName"
+              url:
+                $ref: "#/components/schemas/BroodUrl"
+              description:
+                $ref: "#/components/schemas/BroodDescription"
+              organisation_id:
+                $ref: "#/components/schemas/ID"
+              trusted:
+                $ref: "#/components/schemas/BroodIsTrusted"
+              pull:
+                $ref: "#/components/schemas/BroodIsPull"
+              skip_proxy:
+                type: boolean
+              authkey:
+                $ref: "#/components/schemas/AuthKey"
+
+    EditBroodRequest:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              uuid:
+                $ref: "#/components/schemas/UUID"
+              name:
+                $ref: "#/components/schemas/BroodName"
+              url:
+                $ref: "#/components/schemas/BroodUrl"
+              description:
+                $ref: "#/components/schemas/BroodDescription"
+              organisation_id:
+                $ref: "#/components/schemas/ID"
+              trusted:
+                $ref: "#/components/schemas/BroodIsTrusted"
+              pull:
+                $ref: "#/components/schemas/BroodIsPull"
+              skip_proxy:
+                type: boolean
+              authkey:
+                $ref: "#/components/schemas/AuthKey"
+
   responses:
     # Individuals
     IndividualResponse:
@@ -1337,6 +1590,21 @@ components:
           schema:
             $ref: "#/components/schemas/SharingGroupList"
 
+    # Broods
+    BroodResponse:
+      description: "Brood response"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Brood"
+
+    BroodListResponse:
+      description: "Brood list response"
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/BroodList"
+
     # Errors
     ApiErrorResponse:
       description: "Unexpected API error"