Come faccio a implementare la descrizione del servizio REST in modo tipo di contenuto agnostico ?
Sfondo
Sto sviluppando un'API RESTful per l'applicazione Web. Ora questa app è in qualche modo diversa da una soluzione standard di run-of-mills. Questa app utilizza un SIP B2BUA (asterisco), PHP + Mysql su Apache & NodeJS.
È una soluzione per call center che utilizza l'asterisco per gestire le chiamate VoIP e uno stack LAMP per l'interfaccia utente.
Architettura
REST richiede che l'applicazione sia senza stato. Tuttavia, a causa della natura stessa di SIP, non può essere al 100% senza stato. In questo modo sto utilizzando NodeJS in determinati punti per mantenere attiva la comunicazione in tempo reale.
Ora, c'è una API REST per tutto questo. È progettato in un modo abbastanza semplice. Hai risorse come utente , chiamata , campagna ecc. E un utente può avviare Verbi HTTP su queste risorse.
Le domande
Ho organizzato l'architettura seguendo il modello MVC. La cosa più importante che ho fatto è applicare Docblocks nel Modello . Quello che segue è un esempio di una classe del genere:
abstract class BaseUserInterface implements Interfaces\UserInterface {
protected $usrType = null;
/**
* This is the constructor
*/
public function __construct(Interfaces\User $usrObj){
$this->usrType = ($usrObj instanceof \Model\Agent) ? 'agent':$this->usrType;
$this->usrType = ($usrObj instanceof \Model\Admin) ? 'admin':$this->usrType;
if($this->usrType === null){
throw new \Framework\APIException(__CLASS__." : Insane Type of User Passed while initiating Interface", 500);
}
//Force docblocks
$methodList = $this->listMethods();
foreach($methodList as $method){
$docblock = $this->describe($method);
if(!$docblock){
throw new \Framework\APIException(__CLASS__." : Contract Violated - Method $method Lacks Documentation", 500);
}
}
} //End __construct
/**
* This is the typeOfInterface
*/
public function typeOfInterface(){ //return whether this is admin or agent interface
return $this->usrType;
} //End typeOfInterface
/**
* This is the listMethods
*/
public function listMethods(){ //Allowed Methods
return get_class_methods($this);
} //End listMethods
/**
* This is the describe
*/
public function describe($methodName){
$methodList = $this->listMethods();
if(!in_array($methodName, $methodList)){
throw new \Framework\APIException(__CLASS__." : Asked To Describe Insane Method - ".$methodName, 400);
}
$class = get_class($this);
$reflector = new \ReflectionClass($class);
$phpdoc = $reflector->getMethod($methodName)->getDocComment();
if($phpdoc){
return $this->docParse($phpdoc);
}
else {
return false;
}
} //End describe
/**
* This is the DocParser
*/
protected function docParse($phpdoc){
$phpdoc = new \phpDocumentor\Reflection\DocBlock($phpdoc);
return $phpdoc->getShortDescription()."<br />";
} //End docParse
abstract public function logout();
Naturalmente, ho dato un'idea dei docblock e non dei docblock completi qui. Fondamentalmente, avrebbero la documentazione necessaria. Ora, tutte le classi nello spazio dei nomi Modello che estenderebbero questa classe dovrebbero utilizzare docblocks che rafforzano la documentazione.
Inoltre, ho una funzione Helper :: convert () che può convertire qualsiasi risultato tra XML e JSON a seconda della richiesta di accettazione dell'utente nell'intestazione HTTP .
Quindi, sono tutto pronto con quello.
Ciò di cui sono completamente confuso è:
1. Voglio che l'utente sia in grado di chiedere Describe() su available methods a un dato resource . Come posso implementarlo tramite le intestazioni HTTP?
-
OPTIONSin HTTP mi dice di rispondere conallowed VERBS on ***this*** resource. -
Voglio avere un gateway comune per l'app. L'utente chiede /index.php. Rispondo con
user, call, campaigne un breve messaggio che dice loro che possono usareGETsu questiresourcesper saperne di più. Quindi su quelle risorse, voglio visualizzareavailable methodsseguito dadescription of the selected methode così via e così via. -
Soprattutto, voglio rispondere nell'intestazione accettata dall'utente se supportata da me.
Come faccio a fare questo seguendo le convenzioni corrette? Inoltre, alcuni riferimenti alle RFC sarebbero molto apprezzati.