De kracht van een API

4 april 2013 Inzichten /

Een API (Application Programming Interface) zorgt ervoor dat de data van je website makkelijk en op de juiste manier beschikbaar is voor externe partijen (of je eigen applicaties).
Je kan een API zien als een extra kanaal om informatie te bezorgen aan je bezoekers. We kennen ondertussen allemaal de klassieke manieren om informatie te delen: Facebook, twitter, nieuwsbrieven, ... 
Maar waarom laten we de bezoeker niet zelf kiezen welke en op welk tijdstip hij deze data wil?

 

Onze case

Voor de website van de Ancienne Belgique concertzaal kregen we de opdracht om de data ook op mobiele toestellen te voorzien. Vaak kiezen we hiervoor een responsive website maar in dit geval wenste de klant een echte 'app', en dit voor iPhone en Android toestellen. Dit bood voordelen zoals offline gebruik, push notificaties en een betere user experience. Hierbij kregen we de hulp van een externe partner (In The Pocket) die de app ging maken. Dit gaf natuurlijk de complexiteit dat bepaalde info vanop de website, die men moet beheren via de backend, ook op deze apps moest voorzien worden.
Natuurlijk dachten we direct aan een API oplossing zodat onze partner de informatie makkelijk kan ophalen en zij deze kunnen gebruiken binnen de app.

Welke services voorzien we bij Wijs voor een API?

- De API
- Technische documentatie
- Een API tool/explorer

De API

Vanaf het begin heeft men bij het bouwen van ForkCMS rekening gehouden met de noodzaak van een API. Zo kunnen we per module (bijvoorbeeld: concerts, artists, blog, ...) gaan voorzien welke functionaliteit en data we willen beschikbaar maken.

Hierbij een voorbeeld om de zaken duidelijk te maken.

http:///api/1.0/?method=artists.getArtists&search=hof
&email=foo@example.com&nonce=1320136792&secret=ed533226...4efd5b2

Als we deze url even dieper bekijken kunnen we de volgende zaken terug vinden
- "/api/1.0/": De versie van de API die je zult gebruiken, we kunnen verschillende versies gebruiken en deze ook zonder problemen naast elkaar gebruiken. Dit is handig als we met een migratieperiode te maken hebben tussen 2 versies.
De service kan online werken op een productie versie en ondertussen kunnen wij nieuwe features en requests ontwikkelen in een volgende versie.
- "method=artists.getArtists": Hier bepalen we welke method, en dus ook informatie, we willen opvragen. In dit geval is dit de artiesten ophalen binnen de artiesten module.
- "search=hof": De parameters die we willen meegeven aan de method die we oproepen. Op deze manier halen we de artiesten op waar we de zoekterm 'hof' in terug vinden. Deze parameters hangen dus af van de method die we oproepen.
- "email=foo@example.com&nonce=1320136792&
secret=ed5332...d5b2
": Deze info zorgt voor de authenticatie van de call. Later keren we hierop terug.

Als alle parameters correct zijn doorgegeven en we hebben één of meerdere resultaten gevonden, kunnen we de data verwachten. We geven hier het voorbeeld in JSON maar dit kan dus even makkelijk in XML.

[
    {
        "meta": {
            "status_code": 200,
            "status": "ok",
            "version": "3.5.0",
            "endpoint": "http:///api/1.0"
        },
        "artist": {
            "id": 1234,
            "name": "'t Hof van Commerce",
            "image_url": null,
            "large_image_url": null,
            "web_url": "http:///nl/artiesten/p/detail/t-hof-van-commerce",
            "website_url": [
                "http://www.thofvancommerce.be/",
                "http://www.myspace.com/thofvancommerce",
                "http://www.facebook.com/pages/t-hof-van-commerce/56369767480"
            ],
            "description": "..."
        }
    }
]

Zoals je kan zien krijgen we de info van de artiest hierbij terug zoals dit voorzien is binnen de method maar krijgen we ook extra info van de API terug.
Hierbij is vooral de status van belang zodat de app weet of alles in orde is, of dat er een antwoord moet gevonden worden als foutmelding.

De authenticatie

De default authenticatie werkt op basis van de API-key. Omdat we zeker willen zijn dat de info veilig is moeten we deze beschermen op de volgende manier:
- We zorgen voor een API-key
- Deze gaan we encrypten door een variabel deel (salt) en een vast deel dat de 2 servers kennen erbij te bertrekken. Op die manier krijgen we dan een nieuwe secret zodat we deze veilig kunnen doorsturen.
Samengevat geeft dit dus: secret = sha1(md5(salt) + md5(email + API key))

In het huidige voorbeeld van AB concerts zijn we afgestapt van de normale manier van werken. Dit omdat er een kans was dat de API publiek ging beschikbaar zijn. Hierbij laten we dus het emailadres bij de parameter vallen maar zorgen we voor verdere security door er andere parameters aan toe te voegen.

Technische documentatie

We voorzien een extra document waarin alle data uitgeschreven staat, zodat de externe partij weet welke data hij kan verwachten. Hierbij een vereenvoudigd XML voorbeeld om de zaken duidelijk te maken:



  
      1337
     
      ...
      http:///the-external-url-to-this-event
      true
     
          tag-1
          tag 2
          tag_3
     

     
          my-image.png
          iVBORw0KGgo5CA...kstdN2AAAAAElFTkSuQmCC
  

Daarnaast omschrijven we dan ook de inhoud van alle velden op de volgende wijze:
tag - The optional list of tags that need to be linked to this event. They may only contain a-z, 0-9, underscores, spaces and dashes.
image - The optional image. If you include the image, then the filename & content are required. The content is a 64 base encoded string of the image contents. Only jpg, png and gif images are allowed.

API tool/explorer

Om het werken met de API te vergemakkelijken, voorzien we een tool om deze te testen.  Je ziet dit vaak bij publieke API's als die van Facebook en Google. We gebruiken de introspectie capaciteiten van PHP om zulke tools te genereren.  Zo'n applicatie laat toe dat de API op allerhande manieren kan worden aangesproken en de externe omgeving volledig kan nagebootst worden.

Met het toevoegen van volgende phpdoc:
    /**
     * This methods fetches the YouTube videos and ABTV videos in one array,
     * sorted by date (desc) for the given artist ID.
     *
     * @return array
     * @param int $artistId.
     * @param string[optional] $resolution The resolution that will be used for the images.
     */
    public static function getArtistVideos($artistId, $resolution = 'iphone_retina')
    {
    ...
    }

bekomen we bijvoorbeeld volgend resultaat in onze tool:

Om zelf even met deze tool te spelen kan je terecht op http://demo.fork-cms.com/api/1.1/client/

Bijkomend voor deze case:

In dit project was er ook een noodzaak aan doorsturen van data na een trigger op de website. In ons geval is dit in de backend, meerbepaald het doorsturen van notifications naar de telefoon van mensen die hierop ingeschreven zijn. Hiervoor zette In The Pocket op zijn beurt ook een API op zodat wij deze vlot kunnen aanspreken:

 

Zoals je ziet kan er heel wat komen kijken bij het opzetten van een API. Maar ook is direct duidelijk wat de mogelijkheden zijn en dat er deze features op termijn zelf nodig zijn voor een site met die omvang.

Bron: http://www.fork-cms.com/knowledge-base/detail/how-does-the-api-work

Lees meer

Nieuwsbrief

Doe zoals meer dan 1700 marketing en design experts en ontvang maandelijks onze nieuwsbrief vol inzichten, tips en verrassende nieuwigheden.