Design.md
1 Typology of URLs 2 ================ 3 4 Object URLs 5 ----------- 6 7 They 8 9 - return a single object on GET 10 - may be PATCH-able (to modify the object) 11 - may be DELETE-able (to... delete the object) 12 13 List URLs 14 --------- 15 16 They 17 18 - return a list of objects on GET (some of them are not GET-able) 19 - may be POST-able (to create a new object) 20 - may have specific URLs for their elements, that 21 - may be PUT-able (to add an existing object to this list) 22 - may be GET-able (to ask if an object is in the list) 23 - may be DELETE-able (to remove an object from the list) 24 25 Laziness 26 ======== 27 28 An URL returning a list of objects returns most of the information 29 about its elements, but not all. So, we have a lazy completion for 30 objects returned by the API: we do a GET on their object URL when 31 the user asks an attribute we have not got from the list of objects. 32 33 We don't use lazy completion for objects requested by name by user, 34 to detect name errors as soon as possible. 35 36 Attributes vs. methods 37 ====================== 38 39 We have methods for API calls, and attributes for in-memory reads 40 (except for lazy attributes that may trigger a call to an URL). 41 Methods are named with a verb prefix to avoid name clashes with attributes. 42 (`followers` is an attribute of User giving the number of followers, 43 and `get_followers` is a method returning the list of followers) 44 45 Explicit `edit` methods 46 ======================= 47 48 To modify objects, we have a single `edit` method (not several 49 writable attributes) to be explicit about API calls. 50 51 Typology of attributes 52 ====================== 53 * Internality 54 * Internal (received in the GET request about this object) => attribute (lazy completion if needed) 55 * External (needs another new GET request) => method 56 * Type 57 * Simple type 58 * GithubObject 59 * List of simple type 60 * List of GithubObject 61 * Dict of...