Summering

http://resihop.nu/search (synonym med http://resihop.nu)

Parametrar (en eller flera går att utelämna):

• from - adress
• to - adress
• when - ISO-standard (YYYY-MM-DD)
• got_car - 1 = söker någon som har bil, 0 = söker någon som inte har bil (behöver skjuts)

http://resihop.nu/addtrip

Parametrar:

• from - adress
• to - adress
• when - ISO-standard (YYYY-MM-DD)
• got_car - 1 = Jag har bil, och letar efter medresenärer, 0 = Jag saknar bil, och letar efter skjuts
• name
• email - Ange en giltig för att kunna återfå koden om den tappas bort
• phone
• details

http://resihop.nu/edittrip

Parametrar:

• code - Den unika kod som autencierar förändringar i resan
• from - adress
• to - adress
• when - ISO-standard (YYYY-MM-DD)
• got_car - 1 = Jag har bil, och letar efter medresenärer, 0 = Jag saknar bil, och letar efter skjuts
• name
• email - Ange en giltig för att kunna återfå koden om den tappas bort
• phone
• details

http://resihop.nu/sendcode

Parameter:

• email - Den email som ska få sin(a) kod(er) skickad

Utvecklingsgränssnitt

Vill du bara prova på API:et, så använd domänen dev.resihop.nu. Där behöver du inte vara rädd för att lägga in slaskdata; vi rensar löpande.

Full dokumentation - Index

Grundläggande principer

• Vad är ett API?
• Http-anrop
• URL
• Parametrar
• XML

Resihops teknologi

• Förkunskapskrav
• Om resihop
• Generellt om API:et
• Vår implementation av API:et
• Testmiljö
• Funktionerna
• Ett exempel

Kodex/ordlista

• Nodträdet
• Meta
• Sök
• Spara resa
• Redigera och ta bort resa
• Glömt koden

Grundläggande principer

Vad är ett API?

Api står för "Application programming interface", dvs ett sätt för andra program och system kommer åt vår information (till exempel vilka resor som finns på resihop.nu) och våra funktioner (som sökning och sparning av resor).

Http-anrop

Utan att veta om det gör du säkert flera hundra http-anrop om dagen. Ett http-anrop görs till exempel när du besöker en hemsida. Om du skriver http://resihop.nu/ i din webbläsare, så anropas sidan med hjälp av protokollet http och som svar får du vår startsida!

URL

URL står för Uniform Resource Locator, och är adressen som berättar vilket http-anrop som ska göras. http://resihop.nu/ är tillexempel en URL.

Parametrar

En URL kan innehålla parametrar. De krokas på i slutet av adressen med ett frågetecken, till exempel innehåller

http://resihop.nu/search?from=stockholm

parametern from och parameterns värde är "stockholm". Ifall man vill skicka med flera parametrar så gör man det med hjälp av ett &-tecken. Den här adressen innehåller två parametrar:

http://resihop.nu/search?from=stockholm&to=göteborg.

XML

XML är ett dataformat. All interaktion med resihop.nu får svar i form av XML-filer. Det är viktigt att ha en viss förståelse för XML om man ska använda resihop.nu:s API.

Om resihops teknologi

Förkunskapskrav

• XML-konvertering
• Förståelse för http
• Något att konvertera xml med, t.ex. xslt, ruby, php eller något Content-management-system som kan importera xml.
• Om du inte känner till de här begreppen kan du läsa lite om grunderna här.

Om resihop

Resihop är en teknisk plattform för att hitta och dela med sig av tomma bilplatser för att spara på miljön och plånboken. Det finns väldigt många system och hemsidor för samåkning, vi försöker bidra med att samla alla de resor som finns där ute och dessutom göra dem lättare att söka bland med hjälp av vår platsmedvetna sökmotor.

Hela vår sida och all funktionalitet är byggt med vårt eget API. Ni kan alltså bygga minst lika bra saker som vi har byggt! Hör gärna av er till oss om ni har några frågor eller funderingar.

Generellt om API:et

Det finns 4 funktioner i API:et. De anropas med hjälp av http. Alla anrop besvaras med en xml-fil. För att interagera med vårt system måste varje http-anrop också få med parametrar.

Vår implementation av API:et

Vi har valt att använda xslt för att modifiera xml-koden för resihop. Om du på någon sida på resihop.nu, väljer att visa källan, kommer du därför att se xml-koden som API:et skickar ut.

Testmiljö

Vi har en testversion av API:et med en separat databas på dev.resihop.nu. Använd den för att testa din integrering, så inte felaktiga resor sparas i live-versionen av siten. Du kommer åt testmiljön gör du genom att lägga till ”dev.” i alla http-anrops. OBS! Spara ingen viktig information på dev.resihop.nu, den kan försvinna när som helst.

Funktionerna

Sök

Vår sökmotor vet var alla platser är. Det gör att vi kan göra smarta sökningar, där resihop förstår vilka städer och adresser som ligger nära varandra. Letar du tillexempel efter en resa mellan Uppsala och Göteborg, får du också förslag på resor från Stockholm och Göteborg. Sökmotorn har platser i hela världen och är inte begränsad till Sverige.

Läs mer sökmotorn och hur den fungerar i kodexen.

Spara resa

Att spara resor är enkelt. Det krävs ingen inloggning eller autenciering. När man sparar en resa får man tillbaka en kod som sen kan användas för att redigera resan.

Läs mer om spara-resa-funktionen och hur den fungerar i kodexen.

Redigera och ta bort resa

Att redigera en resa görs på ungefär samma sätt som man sparar en resa, med skillnaden att man också skickar med en kod som en parameter.

Läs mer om redigera-resa-funktionen och hur den fungerar i kodexen.

Glömt koden

När man sparar en resa får man en kod som kan användas för att redigera resan senare. Om man glömt en kod kan man skicka sin E-post adress till resihop. Då skickar resihop ut koden för alla resor kopplade till den E-post-adressen.

Läs mer om glömt-koden-funktionen och hur den fungerar i kodexen.

Ett exempel

Om du gör http-anropet http://resihop.nu/search?to=stockholm&from=lund får du som svar något i stil med:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="/xsl/search.xsl"?>
<root>
  <meta>
    <protocol>http</protocol>
    <domain>resihop.nu</domain>
    <base>/</base>
    <path>search</path>
    <action>index</action>
    <controller>search</controller>
    <url_params>
      <from>lund</from>
      <to>stockholm</to>
      <when></when>
      <got_car>0</got_car>
    </url_params>
    <version>2.0</version>
    <errors>
      <error>
        <message>Invalid format</message>
        <data>
          <param>when</param>
        </data>
      </error>
    </errors>
  </meta>
  <content>
    <trips>
      <trip>
        <trip_id>260</trip_id>
        <from_lon>59.3328</from_lon>
        <from_lat>18.0645</from_lat>
        <to_lon>57.6970</to_lon>
        <to_lat>11.9865</to_lat>
        <when>1288216800</when>
        <got_car>0</got_car>
        <details>öakjf</details>
        <inserted>1288103029</inserted>
        <name>Kristoffer Nolgren</name>
        <email>kristoffer@nolgren.se</email>
        <phone>0704649797</phone>
        <from>Lund, Sweden</from>
        <to>Stockholm, Sweden</to>
        <when_iso>2010-10-28 00:00</when_iso>
      </trip>
      <trip>
        <trip_id>274</trip_id>
        <from_lon>59.3328</from_lon>
        <from_lat>18.0645</from_lat>
        <to_lon>57.6970</to_lon>
        <to_lat>11.9865</to_lat>
        <when>1288216800</when>
        <got_car>0</got_car>
        <details>öakjf</details>
        <inserted>1288111539</inserted>
        <name>Kristoffer Nolgren</name>
        <email>kristoffer@nolgren.se</email>
        <phone>0704649797</phone>
        <from>Lund, Sweden</from>
        <to>Stockholm, Sweden</to>
        <when_iso>2010-10-28 00:00</when_iso>
      </trip>
    </trips>
  </content>
</root>

I vår kodex förklaras hur såväl parametrarna som noderna fungerar.

Kodex/Ordlista

I den här ordlistan beskrivs alla de noder, funktioner och meddelanden man får och kan skicka när man interagerar med resihops API.

Nodträdet

Nodträdet är indelat i meta och Content. Eftersom meta fungerar likadant i varje funktion, medan content varierar från funktion till funktion.

Meta

Xml-noder

Exempel

I exemplet nedan syns metanoden från http-anropet:

http://resihop.nu/search?to=stockholm&from=lund

kan vi se hur url-en är nerbrutet i olika xml-noder. Dessutom får vi information om att prametern ”when” inte har rätt format.

<meta>
 <protocol>http</protocol>
  <domain>resihop.nu</domain>
  <base>/</base>
  <path>search</path>
  <action>index</action>
  <controller>search</controller>
  <url_params>
    <from>lund</from>
    <to>stockholm</to>
    <when></when>
    <got_car>0</got_car>
  </url_params>
  <version>2.0</version>
  <errors>
    <error>
      <message>Invalid format</message>
      <data>
        <param>when</param>
      </data>
    </error>
  </errors>
</meta>

Sök

Vår sökmotor vet var alla platser är. Det gör att vi kan göra smarta sökningar, där resihop förstår vilka städer och adresser som ligger nära varandra. Letar du tillexempel efter en resa mellan Uppsala och Göteborg, får du också förslag på resor från Stockholm och Göteborg. Sökmotorn har platser i hela världen och är inte begränsad till Sverige.

HTTP-anrop

http://resihop.nu/search

Parametrar och felmeddelanden

Ingen av dessa parametrar är obligatoriska för att göra en sökning.

Noder

Exempel

Om vi gör http-anropet

http://resihop.nu/search?from=Stockholm, sweden&got_car=0

kan vi kan vi se att fältet when har fel format, eftersom det är tomt, men trots det får vi två sökresultat, ett från Gnesta och ett från Stockholm. Detta beror på att when inte är ett obligatoriskt fält.

<root>
  <content>
    <trips>
      <trip>
        <trip_id>261</trip_id>
        <from_lon>57.6970</from_lon>
        <from_lat>11.9865</from_lat>
        <to_lon>58.3912</to_lon>
        <to_lat>13.8473</to_lat>
        <when>1289084400</when>
        <got_car>0</got_car>
        <details></details>
        <inserted>1286882091</inserted>
        <name>Filippa Levemark</name>
        <email>filippa.levemark@gmail.com</email>
        <phone>0702910528</phone>
        <from>Stockholm, Sweden</from>
        <to>Skövde, Sweden</to>
        <when_iso>2010-11-07 00:00</when_iso>
      </trip>
      <trip>
        <trip_id>259</trip_id>
        <from_lon>59.3328</from_lon>
        <from_lat>18.0645</from_lat>
        <to_lon>55.6763</to_lon>
        <to_lat>12.5681</to_lat>
        <when>1289516400</when>
        <got_car>0</got_car>
        <details>Jag söker resa från Stockholm till Köpenhamn/ Malmö någon gång 10-12/11. Kan bidra med muntra samtal och bensinpeng.</details>
        <inserted>1286451583</inserted>
        <name>Elin Jonzon</name>
        <email>e_jonzon@hotmail.com</email>
        <phone>0704073504</phone>
        <from>Gnesta, Sweden</from>
        <to>Copenhagen, Denmark</to>
        <when_iso>2010-11-12 00:00</when_iso>
      </trip>
    </trips>
  </content>
</root>

Spara resa

Att redigera en resa görs på ungefär samma sätt som man sparar en resa, med skillnaden att man också skickar med en kod som en parameter.

HTTP-anrop

http://resihop.nu/addtrip

Parametrar och felmeddelanden

Parametrar med en asterix är obligatoriska.

Noder

Exempel

Om vi gör http-anropet

http://resihop.nu/addtrip?from=stockholm&to=göteborg&when=2010-10-28&name=Kristoffer+Nolgren&email=kristoffer%40nolgren.se&phone=0704649797&details=Oavsett+hur+många+vi+blir+så+delar+vi+på+500+kronor+i+resekostnad.&got_car=0

Får vi mycket riktigt ett svar med alla detaljer för resan.

<root>
  <content>
    <new_trip>
      <trip_id>270</trip_id>
      <from>Stockholm, Sweden</from>
      <from_lat>18.0645</from_lat>
      <from_lon>59.3328</from_lon>
      <to>Gothenburg, Sweden</to>
      <to_lat>11.9865</to_lat>
      <to_lon>57.6970</to_lon>
      <when>1288216800</when>
      <when_iso>2010-10-28 00:00</when_iso>
      <details>Oavsett hur många vi blir så delar vi på 500 kronor i resekostnad.</details>
      <got_car>0</got_car>
      <inserted>1288191470</inserted>
      <name>Kristoffer Nolgren</name>
      <email>kristoffer@nolgren.se</email>
      <phone>0704649797</phone>
      <code>CEAD5HEW29TC</code>
    </new_trip>
  </content>
</root>

Redigera och ta bort resa

Att spara resor är enkelt. Det krävs ingen inloggning eller autenciering. När man sparar en resa får man tillbaka en kod som sen kan användas för att redigera resan. För att ändra en resa, skicka med de parametrar du vill ändra, samt den unika koden för din resa. Tomma parametrar bevaras som de är. För att ta bort en resa, skicka parametern remove.

HTTP-anrop

http://resihop.nu/edittrip

Parametrar och felmeddelanden

Parametrar med en asterix är obligatoriska.

Noder

Exempel

Om vi gör http-anropet

http://resihop.nu/edittrip?from=Stockholm,+Sverige&to=Göta+älv,+Sweden&when=2010-10-30+00:00&name=Kristoffer+Nolgren&email=kristoffer%40nolgren.se&phone=0704649797&details=tada!&got_car=1&code=924JZ23HR9RT

får vi mycket riktigt ett svar med alla detaljer för resan.

<root>
  ...
  <content>
    <message>Data saved</message>
    <trip_data>
      <trip_id>279</trip_id>
      <from>Stockholm, Sweden</from>
      <from_lat>18.0645</from_lat>
      <from_lon>59.3328</from_lon>
      <to>Göta älv, Sweden</to>
      <to_lat>12.1229</to_lat>
      <to_lon>58.0267</to_lon>
      <when>1288389600</when>
      <when_iso>2010-10-30 00:00</when_iso>
      <details>tada!</details>
      <got_car>1</got_car>
      <inserted>1288192097</inserted>
      <name>Kristoffer Nolgren</name>
      <email>kristoffer@nolgren.se</email>
      <phone>0704649797</phone>
    </trip_data>
  </content>
</root>

Om vi däremot gör http-anropet

http://resihop.nu/edittrip?remove&code=924JZ23HR9RT

får vi en content nod med innehållet:

<root>
  ...
  <content>
    <message>Data saved</message>
    <trip_data>
      <trip_id>279</trip_id>
      <from>Stockholm, Sweden</from>
      <from_lat>18.0645</from_lat>
      <from_lon>59.3328</from_lon>
      <to>Göta älv, Sweden</to>
      <to_lat>12.1229</to_lat>
      <to_lon>58.0267</to_lon>
      <when>1288389600</when>
      <when_iso>2010-10-30 00:00</when_iso>
      <details>tada!</details>
      <got_car>1</got_car>
      <inserted>1288192097</inserted>
      <name>Kristoffer Nolgren</name>
      <email>kristoffer@nolgren.se</email>
      <phone>0704649797</phone>
    </trip_data>
  </content>
</root>

Glömt koden

Om man glömt en kod kan man skicka sin e-post adress till resihop. Då skickar resihop ut koden för alla resor kopplade till den e-post-adressen.

HTTP-anrop

http://resihop.nu/sendcode

Parametrar och felmeddelanden

Parametrar med en asterix är obligatoriska.

Noder

Exempel

Om vi gör http-anropet

http://resihop.nu/sendcode?email=kristoffer@nolgren.se 

får vi ett meddelande om att koden är sänd

<root>
  ...
  <content>
    <message>Code sent</message>
  </content>
</root>