Work in progress

CHANGES.md

@@ -3,6 +3,11 @@
 ## Features
 
 - New route in Locale API to fetch a list of languages
+- New and consistent response format for all API object + new response examples in the docs
+  - Removed user roles attribute from user object (can be fetched from /v1/teams/memberships) **
+  - Removed type attribute from session object response (used only internally)
+  - ** - might be changed before merging to master
+  
 
 ## Bug Fixes
 

app/controllers/api/account.php

@@ -44,7 +44,6 @@ $utopia->init(function() use (&$oauth2Keys) {
         $oauth2Keys[] = 'oauth2'.ucfirst($key);
         $oauth2Keys[] = 'oauth2'.ucfirst($key).'AccessToken';
     }
-
 });
 
 $utopia->post('/v1/account')
@@ -133,17 +132,7 @@ $utopia->post('/v1/account')
                 ->setParam('resource', 'users/'.$user->getId())
             ;
 
-            $response
-                ->setStatusCode(Response::STATUS_CODE_CREATED)
-                ->json(array_merge($user->getArrayCopy(array_merge(
-                    [
-                        '$id',
-                        'email',
-                        'registration',
-                        'name',
-                    ],
-                    $oauth2Keys
-                )), ['roles' => Authorization::getRoles()]));
+            $response->dynamic($user);
         }
     );
 
@@ -232,8 +221,9 @@ $utopia->post('/v1/account/sessions')
                 ->addCookie(Auth::$cookieName.'_legacy', Auth::encodeSession($profile->getId(), $secret), $expiry, '/', COOKIE_DOMAIN, ('https' == $protocol), true, null)
                 ->addCookie(Auth::$cookieName, Auth::encodeSession($profile->getId(), $secret), $expiry, '/', COOKIE_DOMAIN, ('https' == $protocol), true, COOKIE_SAMESITE)
                 ->setStatusCode(Response::STATUS_CODE_CREATED)
-                ->json($session->getArrayCopy(['$id', 'type', 'expire']))
             ;
+
+            $response->dynamic($session);
         }
     );
 
@@ -535,16 +525,7 @@ $utopia->get('/v1/account')
     ->label('sdk.response', ['200' => 'user'])
     ->action(
         function () use ($response, &$user, $oauth2Keys) {
-            $response->json(array_merge($user->getArrayCopy(array_merge(
-                [
-                    '$id',
-                    'email',
-                    'emailVerification',
-                    'registration',
-                    'name',
-                ],
-                $oauth2Keys
-            )), ['roles' => Authorization::getRoles()]));
+            $response->dynamic($user);
         }
     );
 

src/Appwrite/Response/Response.php

@@ -2,20 +2,89 @@
 
 namespace Appwrite\Response;
 
-use Appwrite\Database\Document;
 use Exception;
+use Appwrite\Database\Document;
+use Appwrite\Response\Results\User;
 use Utopia\Response as UtopiaResponse;
 
 class Response extends UtopiaResponse
 {
+
+    public function __construct()
+    {
+        $this
+            ->setResult(new User)
+        ;
+    }
+
     /**
      * HTTP content types
      */
     const CONTENT_TYPE_YAML = 'application/x-yaml';
 
-    public function dynamic(Document $document)
+    /**
+     * List of defined output objects
+     */
+    protected $results = [];
+
+    /**
+     * Set Result Object
+     * 
+     * @return self
+     */
+    public function setResult(Result $result): self
     {
-        # code...
+        $this->results[$result->getCollection()] = $result;
+
+        return $this;
+    }
+
+    /**
+     * Get Result Object
+     * 
+     * @return Result
+     */
+    public function getResult(string $key): Result
+    {
+        if(!isset($this->results[$key])) {
+            throw new Exception('Undefined result');
+        }
+
+        return $this->results[$key];
+    }
+
+    /**
+     * Validate response objects and outputs
+     *  the response according to given format type
+     */
+    public function dynamic(Document $document, $type = self::CONTENT_TYPE_JSON)
+    {
+        $collection = $document->getCollection();
+        $data       = $document->getArrayCopy();
+        $result     = $this->getResult($collection);
+        $output     = [];
+
+        foreach($result->getRules() as $key => $rule) {
+            if(!isset($data[$key])) {
+                throw new Exception('Missing result key');
+            }
+
+            $output[$key] = $data[$key];
+        }
+
+        switch ($type) {
+            case self::CONTENT_TYPE_JSON:
+                return $this->json($output);
+                break;
+            
+            case self::CONTENT_TYPE_YAML:
+                return $this->yaml($output);
+                break;
+            
+            default:
+                throw new Exception('Unknown content type');
+                break;
+        }
     }
 
     /**

src/Appwrite/Response/Result.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Appwrite\Response;
+
+abstract class Result
+{
+    protected $rules = [];
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    abstract public function getName():string;
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    abstract public function getCollection():string;
+
+    /**
+     * Get Rules
+     * 
+     * @return string
+     */
+    public function getRules(): array
+    {
+        return $this->rules;
+    }
+
+    /**
+     * Add a New Rule
+     */
+    protected function addRule(string $key, string $type, string $description, string $example): self
+    {
+        $this->rules[$key] = [
+            'type' => $type,
+            'description' => $description,
+            'example' => $example,
+        ];
+
+        return $this;
+    }
+}

src/Appwrite/Response/Results/File.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class File extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'User ID.', '5e5ea5c16897e')
+            ->addRule('name', 'string', 'User name.', 'John Doe')
+            ->addRule('email', 'string', 'User email address.', 'john@appwrite.io')
+            ->addRule('emailVerification', 'string', 'Email verification status.', true)
+            ->addRule('registration', 'integer', 'User registration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'User';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/Files.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class Files extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'User ID.', '5e5ea5c16897e')
+            ->addRule('name', 'string', 'User name.', 'John Doe')
+            ->addRule('email', 'string', 'User email address.', 'john@appwrite.io')
+            ->addRule('emailVerification', 'string', 'Email verification status.', true)
+            ->addRule('registration', 'integer', 'User registration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'User';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/Health.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class Health extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'User ID.', '5e5ea5c16897e')
+            ->addRule('name', 'string', 'User name.', 'John Doe')
+            ->addRule('email', 'string', 'User email address.', 'john@appwrite.io')
+            ->addRule('emailVerification', 'string', 'Email verification status.', true)
+            ->addRule('registration', 'integer', 'User registration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'User';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/Logs.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class Logs extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'Session ID.', '5e5ea5c16897e')
+            ->addRule('expire', 'integer', 'Session expiration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'Session';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/Prefs.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class Prefs extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'User ID.', '5e5ea5c16897e')
+            ->addRule('name', 'string', 'User name.', 'John Doe')
+            ->addRule('email', 'string', 'User email address.', 'john@appwrite.io')
+            ->addRule('emailVerification', 'string', 'Email verification status.', true)
+            ->addRule('registration', 'integer', 'User registration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'User';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/Session.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class Session extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'Session ID.', '5e5ea5c16897e')
+            ->addRule('expire', 'integer', 'Session expiration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'Session';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/Sessions.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class Sessions extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'Session ID.', '5e5ea5c16897e')
+            ->addRule('expire', 'integer', 'Session expiration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'Session';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/Token.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class Token extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'Token ID.', '5e5ea5c16897e')
+            ->addRule('expire', 'integer', 'Token expiration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'User';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}

src/Appwrite/Response/Results/User.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Appwrite\Response\Results;
+
+use Appwrite\Database\Database;
+use Appwrite\Response\Result;
+
+class User extends Result
+{
+    public function __construct()
+    {
+        $this
+            ->addRule('$id', 'string', 'User ID.', '5e5ea5c16897e')
+            ->addRule('name', 'string', 'User name.', 'John Doe')
+            ->addRule('email', 'string', 'User email address.', 'john@appwrite.io')
+            ->addRule('emailVerification', 'string', 'Email verification status.', true)
+            ->addRule('registration', 'integer', 'User registration date in UNIX format.', 1583261121)
+        ;
+    }
+
+    /**
+     * Get Name
+     * 
+     * @return string
+     */
+    public function getName():string
+    {
+        return 'User';
+    }
+
+    /**
+     * Get Collection
+     * 
+     * @return string
+     */
+    public function getCollection():string
+    {
+        return Database::SYSTEM_COLLECTION_TOKENS;
+    }
+}