Bimba.git

commit 65df18cd9983af2f0dc626bfe4dedc343eb470dc

Author: Adam Pioterek <adam.pioterek@protonmail.ch>

api draft

 research/api.bimba.tk.yml | 622 +++++++++++++++++++++++++++++++++++++++++
 todo | 1 


diff --git a/research/api.bimba.tk.yml b/research/api.bimba.tk.yml
new file mode 100644
index 0000000000000000000000000000000000000000..8cf5b05c7dba6e17d7f69bfbd5fcfdad46f47e99
--- /dev/null
+++ b/research/api.bimba.tk.yml
@@ -0,0 +1,622 @@
+name: Bimba API
+version-code: 0.1.0
+version-name: Agrajag
+status: draft
+formats: &formats
+  msgpack: msgpack
+errors:
+  _general: &_general-error
+    error:
+      type: str
+  _fields: &_fields-error
+    fields:
+      required: false
+      type: list
+      items:
+        type: dict
+        items:
+          field:
+            type: str
+          error:
+            type: str
+  error_general: &error_general
+    type: dict
+    items:
+      *_general-error
+  error_fields: &error_fields
+    type: dict
+    items:
+        <<: *_general-error
+        <<: *_fields-error
+
+api:
+-
+  path: /timetables/
+  GET:
+    description: list of dates (from,to)
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+          type: list
+          items:
+            type: dict
+            items:
+              id:
+                type: str
+              start:
+                type: str:RFC_3339_full-date
+              end:
+                type: str:RFC_3339_full-date
+  POST:
+    description: new timetable [locked]
+    req:
+      headers:
+        - Accept
+        - Authorization (Signature {signature})
+        - Content-Type
+      schema: todo
+    res:
+      codes:
+        - 201
+        - 400
+        - 401
+        - 403
+        - 406
+        - 409  # already exists for the period
+      headers:
+        - Allow
+        - WWW-Authenticate
+        - Content-Type
+        - Location
+      schema:
+        *error_fields
+  DELETE:
+    description: remove timetable [locked]
+    req:
+      headers:
+        - Accept
+        - Authorization (Signature {signature})
+    res:
+      codes:
+        - 204
+        - 401
+        - 403
+        - 406
+        - 410
+      headers:
+        - Allow
+        - WWW-Authenticate
+        - Content-Type
+      schema:
+        *error_general
+
+-
+  path: /timetables/:date:(`current`|RFC_3339_full-date)
+  GET:
+    description: timetable valid in :date full with metadata
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+        - 410  # past date
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema: todo
+      
+-
+  path: /timetables/:date/lines/
+  GET:
+    description:
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+        - 410  # past date
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: list
+        items:
+          type: dict
+          items:
+            name:
+              type: str
+            directions:
+              type: list
+              items:
+                type: int
+
+-
+  path: /timetables/:date/lines/:number?direction:(0|1)=null
+  GET:
+    description: line graph <filtered by direction>
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+        - 410  # past date
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: list
+        items:
+          type: dict
+          items:
+            direction:  # (0|1)
+              type: int
+            components:
+              type: list
+              items:
+                type: dict
+                items:
+                  main:
+                    type: bool
+                  stops:
+                    type: list
+                    items:
+                      type: dict
+                      items:
+                        code:
+                          type: str
+                        name:
+                          type: str
+                  
+-
+  path: /timetables/:date/stops/?q:query=''
+  GET:
+    description: list of stops matching latinised, case insensitive ^.*q.*$; sorted by relevance and limited to N=10?
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+        - 410  # past date
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: list
+        items:
+          type: dict
+          items:
+            name:
+              type: str
+            code:
+              type: str
+            lines:
+              type: list
+              items:
+                type: str  # {line} → {headsign}
+
+-
+  path: /timetables/:date/stops/:name/sheds/
+  reason: is neccessary?
+  
+-
+  path: /timetables/:date/stops/:name/sheds/:code
+  reason: is neccessary?
+
+-
+  path: /timetables/:date/departures/sheds/:code?metadata:bool=false  # todo: metadata schema
+  GET:
+    description: departures for whole shed
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+        - 410  # past date
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema: &departure
+        type: list
+        items:
+          type: dict
+          items:
+            line:
+              type: str
+            headsign:
+              type: str
+            time:
+              type: int  # seconds after midnight
+            modifications:
+              type: list
+              items:
+                type: str
+            accessible:  # low floor
+              type: bool
+
+-
+  path: /timetables/:date/departures/sheds/:code/lines/:number?metadata:bool=false  # todo: metadata schema
+  GET:
+    description: departures for whole line in shed
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+        - 410  # past date
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        *departure
+
+-
+  path: /timetables/:date/departures/sheds/:code/lines/:number/headsigns/:headsign?metadata:bool=false  # todo: metadata schema
+  GET:
+    description: departures for whole line with headsign in shed
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+        - 410  # past date
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        *departure
+
+-
+  path: /information/(news|alerts)/
+  GET:
+    description: list of ID, title, source, date, translations, thumbnail
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: list
+        items:
+          type: dict
+          items:
+            id:
+              type: str
+            title:
+              type: str
+            source:
+              type: str  # URL
+            datetime:
+              type: str  # RFC3339
+            translations:
+              type: list
+              items:
+                type: str  # IETF language tag
+            thumbnail:  # preferably webp
+              type: bytes
+
+-
+  path: /imformation/*/:id
+  GET:
+    description: original text of the piece of information
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: dict
+        items:
+          content:
+            type: str  # ReStructuredText?
+          lang:
+            type: str  # IETF language tag
+
+-
+  path: /information/*/:id/translations/
+  GET:
+    description: list of translations (ID, lang)
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: list
+        items:
+          type: dict
+          items:
+            id:
+              type: str
+            lang:
+              type: str  # IETF language tag
+  POST:
+    description: create new translation
+    req:
+      headers:
+        - Accept
+        - Content-Type
+      schema:
+        type: dict
+        items:
+          content:
+            type: str
+          lang:
+            type: str  # IETF language tag
+    res:
+      codes:
+        - 201
+        - 400
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - Location
+      schema:
+        *error_fields
+
+-
+  path: /information/*/:id/translations/:id
+  GET:
+    description: translations content and score
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: dict
+        items:
+          content:
+            type: str
+          lang:
+            type: str  # IETF language tag
+          score:
+            type: float
+  PATCH:
+    description: assess translation
+    req:
+      headers:
+        - Accept
+        - Content-Type
+      schema:
+        type: dict
+        items:
+          vote:
+            type: float
+    res:
+      codes:
+        - 200
+        - 400
+        - 404
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - Location
+      schema:
+        *error_fields
+
+-
+  path: /crash_reports/
+  GET:
+    description: list of crash reports (date, id)
+    formats:
+      <<: *formats
+      atom: atom
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: list
+        items:
+          type: dict
+          items:
+            id:
+              type: str
+            date:
+              type: str  # RFC3339
+  POST:
+    description: new crash report
+    req:
+      headers:
+        - Accept
+        - Content-Type
+      schema:
+        type: dict
+        items: &crash_report
+          app:  # web,apk,…
+            type: str
+          app_version:
+            type: str
+          conetxt:  # apk:OS, web:browser
+            type: str
+          context_version:  # apk:Android API level (ROM?), web:browser version
+            type: str
+          device:  # apk:make,model,…, web:?
+            type: str
+          content:  # staktrace, &c.
+            type: str
+    res:
+      codes:
+        - 201
+        - 400
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - Location
+      schema:
+        *error_fields
+
+-
+  path: /crash_reports/:id
+  GET:
+    description: crash report
+    req:
+      headers:
+        - Accept
+        - If-None-Match
+    res:
+      codes:
+        - 200
+        - 304
+        - 404
+        - 406
+      headers:
+        - Allow
+        - Content-Type
+        - ETag
+      schema:
+        type: dict
+        items:
+          <<: *crash_report
+          issue:  # bug tracking issue (e.g. in repo)
+            type: str  # URL
+          updated:
+            type: str  # RFC3339
+  PATCH:
+    description: add info [locked]
+    req:
+      headers:
+        - Accept
+        - Authorization (Signature {signature})
+        - Content-Type
+        - If-Match
+      schema:
+        type: dict
+        items:
+          issue:  # bug tracking issue (e.g. in repo)
+            type: str  # URL
+    res:
+      codes:
+        - 200
+        - 400
+        - 401
+        - 403
+        - 406
+        - 412
+        - 428
+      headers:
+        - Allow
+        - WWW-Authenticate
+        - Content-Type
+        - Location
+      schema:
+        *error_fields
+  DELETE:
+    description: remove [locked]
+    req:
+      headers:
+        - Accept
+        - Authorization (Signature {signature})
+    res:
+      codes:
+        - 204
+        - 401
+        - 403
+        - 406
+        - 410
+      headers:
+        - Allow
+        - WWW-Authenticate
+        - Content-Type
+      schema:
+        *error_general




diff --git a/todo b/todo
index 48a6c79ed5f0f796aa1ad540a9ca20d6e70c12b1..ab55c2de9ec0242bc16fc1fb6d1fc3a47923c1da 100644
--- a/todo
+++ b/todo
@@ -13,3 +13,4 @@ x search results flickering
 - favourite cache
 v in a moment
 - departures sort (timeTill, onStop) : StopActivity
+- sort and limit search results