Start » artikelen
04/12/2007 - 16:46
Altijd al een SWX of remoting API willen hebben van je favoriete dienst ? De basis benodigdheden zijn wat kennis van php en een gateway. En uiteraard moet de Dienst, waarvoor je een Service schrijft, beschikken over een API waar je de eigen SWX/Remoting Service op aan te sluiten. Twitter, Jaiku, Numpa en andere microlog services hebben allemaal een API. Voor dit artikel gaan we aan de slag met de API(PDF Alert) van Numpa.nl.

Services API bouwen voor SWX of Flash Remoting

Services API bouwen voor SWX of Flash Remoting

Voorbereiding

Om te beginnen heb je, om te testen, een installatie nodig van SWX PHP.
Hoe je SWX installeert en welke keuzes je daarin hebt kan je lezen in het SWX PHP boek. Je ziet daar tevens een voorbeeld van hoe je een simpele (zonder externe API's) Service maakt.

Aanwezige BaseClass het halve werk

Wanneer je SWX PHP hebt geïnstalleerd kan je in de 'php' map ( swxInstallFolder/php) de BaseService.php vinden. Deze Basis Service gaan we gebruiken om JSON calls te regelen. Bestudeer de Class dus goed voor je begint, zodat je weet wat er daarin gebeurd.

Is er een API van de dienst beschikbaar ?

In dit artikel gaan we uit van de Numpa API. Numpa.nl is de Nederlandse microlog service, waar je net als bij Twitter in 140 tekens/karakters kan vertellen wat je aan het doen bent.

Numpa heeft een API(PDF Alert) en die ziet er als volgt uit:

De numpa API

Berichten posten:URL: http://numpa.nl/api/json.lasso

    Verplichte parameters voor het posten van berichten:

  • - method (type: string, waarde: Message.Post)
    methode die je wilt aanroepen
  • - username (type: string)
    username van de gebruiker
  • - password (type: string)
    wachtwoord van de gebruiker
  • - message (type: string)
    het bericht van maximaal 140 karakters
    Optionele parameters:

  • - location (type: string)
    locatie waar vandaan de gebruiker de berichten post
  • - storeLocation (type: int, waarde: 1 of 0)
    locatie opslaan voor toekomstig gebruik op de site, 1 = ja, 0 = nee (standaard)
  • - postToTwitter (type: int, waarde: 1 of 0)
    bericht doorplaatsen naar Twitter, 1 = ja, 0 = nee (standaard)
  • - postToJaiku (type: int, waarde: 1 of 0)
    bericht doorplaatsen naar Jaiku, 1 = ja, 0 = nee (standaard)

Voorbeeld Response van server (JSON formaat):

  • Succesvolle plaatsing:
    {"jaiku": "ok", "status": "ok", "twitter": "ok"}
  • Foutmelding:
    {"status": "failed", "msg": "Invalid user credentials"}

Berichten ophalen:URL: http://numpa.nl/api/json.lasso

    Verplichte parameters voor het ophalen van berichten:

  • - method (type: string, waarde: Messages.Latest)
    methode die je wilt aanroepen
  • - username (type: string)
    username van de gebruiker
  • - password (type: string)
    wachtwoord van de gebruiker
  • - type (type: string, waarde: public, user of friends)
    geeft aan welk type berichten je wilt ontvangen: de publieke berichten, berichten van
    alléén de gebruiker of berichten van de gebruiker en zijn/haar vrienden
    Optionele parameters

  • amount (type: int, waarde: min. 1 en max. 30)
    hoeveel berichten je wilt ontvangen (standaard 10)
  • - comments (type: int, waarde: 1 of 0)
    berichten ophalen inclusief reacties, 1 = ja, 0 = nee(standaard)

Voorbeeld Response van server (JSON formaat):

  • Foutmelding:
    {"status": "failed", "msg": "Invalid user credentials"}
  • De berichten:
    [{"location": "thuis", "message": "maar nu eerst eten", "avatar":
    "http://numpa.nl/upload/avatars/20070603333333_m.jpg", "date":
    "21/06/2007 16:48", "user": "Tester"}, {"comments": [{"message":
    "Met wie?", "avatar":
    "http://numpa.nl/upload/avatars/20070603333332_m.jpg", "date":
    "21/06/2007 16:50", "user": "master"}], "location": "mobiel",
    "message": "ga zo rennen.. ", "avatar":
    "http://numpa.nl/upload/avatars/20070603333332_m.jpg", "date":
    "21/06/2007 16:47", "user": "Chefke"}]

Nu je ziet wat de Numpa API doet kan je de SWX Services Class bouwen dus laten we beginnen. SWX beschikt over de Data Analyzer en de ServiceBrowser. Twee handige tools die je helpen je Service Class makkelijker en sneller te schrijven en te testen. De Data Analyzer gebruik je samen met je flash movie. De ServiceBrowser helpt je de net geschreven class of class methodes te testen.

De numpa API omzetten in een SWX Service class

Allereerst de basis class neerzetten, sla deze op als NumpaTest.php in de swx php/services folder (LET OP! Er bestaat reeds een Numpa.php in de services folder, overschrijf deze niet en bekijk hem pas na dit artikel.):

<?php
// Require base service class
        require_once("../BaseService.php");
        class NumpaTest extends BaseService
        {
        }
?>

Nu gaan we in de class, drie verschillende service methodes schrijven die gebruik maken van 1 privé functie.
We maken drie Methodes omdat je, bij het berichten halen, 3 verschillende types kan opgeven: (type: string, waarde: public, user of friends).

De prive functie _getMessages

De privé functie neemt als argumenten $user, $pass, $type, $amount en $comments. Met de waardes bereid de functie een json call voor en retourneert die de resultaten.

De private functie om de laatste berichten op te halen voor de 3 Service methodes gaat er dan zo uitzien:

<?php
function _getMessages( $user, $pass, $type, $amount, $comments )
{
  $url = "numpa.nl/api/json.lasso"; //zonder http://
  $vars = array( "method" => "Messages.Latest", "username" => $user, "password" => $pass,
                "type" => $type, "amount"=> $amount, "comments"=> $comments     );
  return $this->_jsonCall($url, $vars, "POST");
}
?>

Met deze privé methode, welke gebruik maakt van de handige BaseService class, hebben we alles wat we nodig hebben om de 3 Service methodes te maken.

De Service methods

Omdat de methode voor berichten ophalen hetzelfde is en we de type in de Service methode naam gaan stoppen, hebben we het type en de method niet nodig als verplichte argumenten.
We houden deze verplichte argumenten over: Gebruikers naam en wachtwoord.
Voor de optionele argumenten zetten we de standaard waarde vast neer.

Allereerst de publieke berichten.

Onderstaande service method is om de laatste publieke berichten van numpa te halen. Let erop! Het commentaar zie je deels terug in de ServiceBrowser.

<?php
/**
 * Returns 10 latest public messages.
 *
 * @param (required) String - Username for your Numpa account
 * @param (required) String - Password for your Numpa account
 * @param (optional) Int - Amount of messages min:1, max:30 default is 10
 * @param (optional) Int - with or without comments 0 (off) or 1 (on) default is 0 (off)
 * @return Array of public update messages.
 * @author Folkert Hielema
 **/
function publicMessages($user = "", $pass = "", $amount = 10, $comments = 0)
{
        $result = $this->_getMessages( $user, $pass, "public", $amount, $comments);
        return $result;
}

Door de BaseService en de privé functie van daarnet is dit alles wat je nodig hebt voor de publieke berichten.

De friends en users Methodes

Zo simpel dat we gelijk de 'vrienden' en de 'user' berichten ook even doen. Je ziet de de genaamde methodes het type standaard ingeven, daardoor hoeft die niet als argument mee in je verzoek (Service call).

<?php
/**
 * Returns 10 latest user messages.
 *
 * @param (required) String - Username for your Numpa account
 * @param (required) String - Password for your Numpa account
 * @param (optional) Int - Amount of messages min:1, max:30 default is 10
 * @param (optional) Int - with or without comments 0 (off) or 1 (on) default is 0 (off)
 * @return Array of user statuses.
 * @author Folkert Hielema
 **/
function userMessages($user = "", $pass = "", $amount = 10, $comments = 0)
{
  $result = $this->_getMessages( $user, $pass, "user", $amount, $comments);
  return $result;
}
/**
 * Returns 10 latest friends messages.
 *
 * @param (required) String - Username for your Numpa account
 * @param (required) String - Password for your Numpa account
 * @param (optional) Int - Amount of messages min:1, max:30 default is 10
 * @param (optional) Int - with or without comments 0 (off) or 1 (on) default is 0 (off)
 * @return Array of friends update messages.
 * @author Folkert Hielema
 **/
function friendsMessages($user = "", $pass = "", $amount = 10, $comments = 0)
{
  $result = $this->_getMessages( $user, $pass, "friends", $amount, $comments);
  return $result;
}

Het complete NumpaTest.php bestand wat je hierdoor krijgt, zie anders verderop, kan nu je publieke berichten,berichten van je vrienden en je eigen berichten ophalen.

<?php
// Require base service class
require_once("../BaseService.php");
class NumpaTest extends BaseService
{
 /**
  * Returns 10 latest public messages.
  *
  * @param (required) String - Username for your Numpa account
  * @param (required) String - Password for your Numpa account
  * @param (optional) Int - Amount of messages min:1, max:30 default is 10
  * @param (optional) Int - with or without comments 0 (off) or 1 (on) default is 0 (off)
  * @return Array of public update messages.
  * @author Folkert Hielema
  **/
  function publicMessages($user = "", $pass = "", $amount = 10, $comments = 0)
  {
    $result = $this->_getMessages( $user, $pass, "public", $amount, $comments);
    return $result;
  }
  /**
   * Returns 10 latest user messages.
   *
   * @param (required) String - Username for your Numpa account
   * @param (required) String - Password for your Numpa account
   * @param (optional) Int - Amount of messages min:1, max:30 default is 10
   * @param (optional) Int - with or without comments 0 (off) or 1 (on) default is 0 (off)
   * @return Array of user statuses.
   * @author Folkert Hielema
   **/
  function userMessages($user = "", $pass = "", $amount = 10, $comments = 0)
  {
    $result = $this->_getMessages( $user, $pass, "user", $amount, $comments);
    return $result;
  }
  /**
   * Returns 10 latest friends messages.
   *
   * @param (required) String - Username for your Numpa a ccount
   * @param (required) String - Password for your Numpa account
   * @param (optional) Int - Amount of messages min:1, max:30 default is 10
   * @param (optional) Int - with or without comments 0 (off) or 1 (on) default is 0 (off)
   * @return Array of friends update messages.
   * @author Folkert Hielema
   **/
  function friendsMessages($user = "", $pass = "", $amount = 10, $comments = 0)
  {
    $result = $this->_getMessages( $user, $pass, "friends", $amount, $comments);
    return $result;
  }
//private method for latest messages
  function _getMessages( $user, $pass, $type, $amount, $comments )
  {
    $url = "numpa.nl/api/json.lasso";
    $vars = array( "method" => "Messages.Latest", "username" => $user, "password" => $pass,
                 "type" => $type, "amount"=> $amount, "comments"=> $comments    );
    return $this->_jsonCall($url, $vars, "POST");
  }
}
?>

En nu verder ?

Maak aan de hand van dit artikel en de reeds bestaande SWX Numpa API, je NumpaTest.php compleet door de Service methodes voor het posten van berichten erin te bouwen. Bestudeer de bestaande SWX Numpa API en de BaseService class hiervoor.

Uiteraard is het ook leuk als je een SWX flash client bouwt die van je nieuwe NumpaTest service gebruik maakt, zo zie je gelijk de grote voordelen van Native Data.
Meer info: Meer over het bouwen van een SWX client

Handige referenties

Meer over SWX:

Vragen en opmerkingen/aanpassingen graag in de reacties. Het artikel kan nog worden bijgewerkt.