Ero sivun ”Journeys API” versioiden välillä

Journeys API (näytä wikiteksti)

Versio 4. heinäkuuta 2014 kello 03.47

2 987 merkkiä lisätty , 4. heinäkuuta 2014 kello 03.47

→‎Queries and Responses

Juha.lundan

approved, byrokraatit, ylläpitäjät

0

muokkausta

@@ Rivi 25: / Rivi 25: @@
 ==Queries and Responses==
+=== REST styled API ===
+Journeys API follows RESTful design pattern. This means that all entities returned by the API have an unique URL via which the entity can be accessed at all times. The returned entities refer to each other via these URLs, and each entity URL is always included in the entity itself as "href" property. Following is a fragment from JOURNEY entity response:
+<pre>
+    "data" : {
+        "href" : "http://example.com/journeys/api/journeys/111",
+        "departureTime" : "08:00:00+0300",
+        "dayTypes" : [
+            {
+                "href" : "http://example.com/journeys/api/day-types/weekdays"
+            }
+        ],
+        "dayTypeExceptions" : [
+            {
+                "href" : "http://example.com/journeys/api/day-type-exceptions/111",
+                "date" : "2014-05-05",
+                "runs" : "no"
+            }
+        ],
+        "calls" : [
+            {
+                "href" : "http://example.com/journeys/api/calls/1123",
+                "arrival" : "08:00:00+0300",
+                "departure" : "08:00:00+0300",
+                "stopPoint" : {
+                    "href" : "http://example.com/journeys/api/stop-points/222"
+                }
+            }
+...
+</pre>
+The JOURNEY itself has a href property (http://example.com/journeys/api/journeys/111) which points to the JOURNEY entity itself. A client can use this URL access this entity at any time. The dayType entity has also an href property which tells the client how to access the DAY TYPE data. Whenever a client encounters a href property in the response, the client should make a HTTP GET request to that url in order to access the entity data. The client the can "attach" the returned data to the original response. Depending on the request, the Journeys API might "expand" a entity in a response. For example, a DAY TYPE EXCEPTION element in the response above contains '''both''' href property as well as "date" and "runs" properties. This means that the client does not need to make a request to the href URL in order to access the entity data. Instead, the Journeys API has already included the full data of the entity into the request.
+<br><br>
+There are no rules when the Journeys API will expand an element (even though typically first level children of an element are typically expanded). Therefore, the client must follow these rules '''at all times'''.
+* If any entity (including nested child entities) contains href property, and no other properties, the client needs to make a HTTP GET request to the URL the href property specifies
+* If any entity (including nested child entities) contains href property, and other properties, the client should not make a HTTP GET request, since Journeys API has already expanded the entity (and all its child entities) in the response. The expanded entity can however contain child entities which have only href property present; in this case, the client is expected to make HTTP GET request for that child entity.
 === API-Wide URL parameters ===
 ==== Time ====