Research and Development 1/2010-11/project/AppCetera/REST API

Introductie

De Mapp API is een RESTful API. Binnen deze architectuur staat elke HTTP methode voor een andere actie op het object.

• PUT - het toevoegen van een nieuw object
• POST - het wijzigen van een bestaand object
• GET - het opvragen van een object
• DELETE - het verwijderen van een object

De voorbeelden in deze documentatie kunnen gebruikt worden door middel van cURL.

Endpoint

De API wordt op dit moment lokaal ontwikkeld en is vooralsnog alleen lokaal te benaderen door server lokaal te draaien. De code voor de server staat op GitHub. In de standaard configuratie heeft de server "mapp-server.dev" als host en is te benaderen over het HTTP protocol.

http://mamp-server.dev/v1/

En draait in (beta) productie op

http://mapp.joelcox.org/v1/

Autorisatie

De meeste resources vereisen autorisatie voordat de client hiertoe toegang toe krijgt. Dit gebeurt door middel van HTTP Basic Authentication. Hierbij vervangt het e-mail adres de gebruikersnaam en is het het wachtwoord de MD5 hash van het door de gebruiker opgegeven wachtwoord.

Met ingang van 24 mei gebruikt de API HTTP Basic authenticatie i.p.v. HTTP Digest
Joël Cox → Research and Development 1	Remove this comment when resolved!

Status codes

Code	Betekenis
200	OK, geen fouten
400	Bad request, één of meerdere parameters niet goed ingevuld
404	Not found, object niet gevonden
500	Internal server error, de server kon het verzoek niet verwerken (database fout of permissies)

Resources

GET time

Seconden sinds Unix Epoch (servertijd)

Voorbeeld

curl http://mapp-server.dev/v1/time

GET user/id/(:int)

Verkrijg gebruikersinformatie met volgens het id, of informatie over de ingelogde gebruiker

Parameters

• id - gebruikers id (optioneel)

Voorbeeld

curl --basic -u test@example.combcd4621d373cade4e832627b4f6 http://mapp-server.dev/v1/user/id/2

Antwoord

{
   "id":"1",
   "email":"test@example.com",
   "password":"098f6bcd4621d373cade4e832627b4f6",
   "groups":[
      {
         "id":"1",
         "accepted":"1"
      },
      {
         "id":"2",
         "accepted":"0"
      }
   ]
}

PUT new_user

Maak een nieuwe gebruiker aan

Parameters

• email
• password

Voorbeeld

curl http://mapp-server.dev/v1/new_user

GET is_registered

Kijk of een e-mail adres geregistreerd is

Voorbeeld

curl http://mapp-server.dev/v1/is_registered/email/test%40example.com

GET polygons/group_id/(:int)/since/(:int)

Alle polygonen binnen een groep, sinds een bepaalde tijd

Parameters

• group_id
• since

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 http://mapp-server.dev/v1/polygons/group_id/1/since/123456789

Antwoord

[
   {
      "id":"1",
      "group_id":"1",
      "name":"Polynaam",
      "color":"bb2200",
      "points":[
         {
            "latitude":"11.231",
            "longitude":"12.331",
            "order":"1"
         },
         {
            "latitude":"5.234",
            "longitude":"52.3243",
            "order":"2"
         }
      ]
   },
   {
      "id":"2",
      "group_id":"1",
      "name":"Polynaam",
      "color":"bb2200",
      "points":[
         {
            "latitude":"11.231",
            "longitude":"12.331",
            "order":"1"
         },
         {
            "latitude":"5.234",
            "longitude":"52.3243",
            "order":"2"
         }
      ]
   }
]

GET polygon/id/(:int)

Parameters

• id

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 http://mapp-server.dev/v1/polygon/id/1

Antwoord

{
   "id":"1",
   "group_id":"1",
   "name":"Polynaam",
   "color":"bb2200",
   "points":[
      {
         "latitude":"11.231",
         "longitude":"12.331",
         "order":"1"
      },
      {
         "latitude":"5.234",
         "longitude":"52.3243",
         "order":"2"
      }
   ]
}

PUT polygon

Maak een nieuwe polygoon

Parameters

• name
• color
• group_id
• description (urlencoded)
• points
  • latitude
  • longitude
  • order

Deze drie parameters worden gescheiden door een comma.

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X PUT --data "name=Polynaam&color=bb2200&group_id=1&description=Testing+1+2+3&points[]=11.231,12.331,1&points[]=5.234,52.3243,2" http://mapp-server.dev/v1/polygon

Antwoord

{
   "polygon_id":8
}

POST polygon

Parameters

• id
• name (optioneel)
• color (optioneel)
• description (urlencoded) (optioneel)
• points
  • latitude
  • longitude
  • order

Deze drie parameters worden gescheiden door een comma.

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X POST --data "id=1&name=Polynaam2&color=333444&description=Testing+6+7+1&points[]=111.231,122.331,1&points[]=55.234,522.3243,2" http://mapp-server.dev/v1/polygon

Antwoord

{
   "message":"Polygon successfully updated"
}

DELETE polygon

Verwijderen een polygoon.

Parameters

• id

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X DELETE --data "id=1" http://mapp-server.dev/v1/polygon

Antwoord

{
   "message":"Polygon successfully deleted."
}

PUT membership

Nodig een lid uit voor groep (alleen voor beheerders van een groep)

Parameters

• user_id
• group_id

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X PUT --data "user_id=2&group_id=2" http://mapp-server.dev/v1/membership

Antwoord

{
   "message":"Membership is set (but not accepted)."
}

POST membership

Accepteer een groepsuitnodiging (voor de ingelogde gebruiker)

Parameters

• group_id

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X POST --data "group_id=1" http://mapp-server.dev/v1/membership

Antwoord

{
   "message":"Membership is accepted."
}

DELETE membership

Zeg een lidmaatschap van een groep op (voor de ingelogde gebruiker)

Parameters

• group_id

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X DELETE --data "group_id=1" http://mapp-server.dev/v1/membership

Antwoord

{
   "message":"Membership successfully deleted."
}

GET group/id/(:int)

Parameters

• id

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 http://mapp-server.dev/v1/group/id/1

Antwoord

{
   "name":"test",
   "email":"wwfg",
   "polygons":"7",
   "members":[
      {
         "email":"wwfg",
         "accepted":"1"
      }
   ]
}

PUT group

Parameters

• name

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X PUT --data "name=Shaala" http://mapp-server.dev/v1/group

Antwoord

{
   "message":"Group successfully created."
}

POST group

Parameters

• id
• name

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X POST --data "name=Shaala2&id=1" http://mapp-server.dev/v1/group

Antwoord

{
   "message":"Group successfully updated."
}

DELETE group

Parameters

• id

Voorbeeld

curl --basic -u test@example.com:098f6bcd4621d373cade4e832627b4f6 -X DELETE --data "id=3" http://mapp-server.dev/v1/group

Antwoord

{
   "message":"Group successfully deleted."
}

Links

JSON formatter & validator