{"action":"created","issue":{"url":"https://api.github.com/repos/liqd/thentos/issues/330","labels_url":"https://api.github.com/repos/liqd/thentos/issues/330/labels{/name}","comments_url":"https://api.github.com/repos/liqd/thentos/issues/330/comments","events_url":"https://api.github.com/repos/liqd/thentos/issues/330/events","html_url":"https://github.com/liqd/thentos/issues/330","id":109967967,"number":330,"title":"API questions","user":{"login":"jkarni","id":1657498,"avatar_url":"https://avatars.githubusercontent.com/u/1657498?v=3","gravatar_id":"","url":"https://api.github.com/users/jkarni","html_url":"https://github.com/jkarni","followers_url":"https://api.github.com/users/jkarni/followers","following_url":"https://api.github.com/users/jkarni/following{/other_user}","gists_url":"https://api.github.com/users/jkarni/gists{/gist_id}","starred_url":"https://api.github.com/users/jkarni/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jkarni/subscriptions","organizations_url":"https://api.github.com/users/jkarni/orgs","repos_url":"https://api.github.com/users/jkarni/repos","events_url":"https://api.github.com/users/jkarni/events{/privacy}","received_events_url":"https://api.github.com/users/jkarni/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2015-10-06T09:23:27Z","updated_at":"2015-10-06T10:05:35Z","closed_at":null,"body":"A lot of questions are popping up related to API design in #229, and that's not quite the right place for all of them. Most of these pertain to thentos-core, since in thentos-adhocracy the API we need is externally constrained much more. \r\n\r\n# When do we return complex objects?\r\n\r\nWe have an endpoint to retrieve user email. Another one to retrieve user name. Why do we split those up, rather than have a single endpoint that returns an object with both? More generally, when do we split up?\r\n\r\nThere are also endpoints that return whether a session exists (a `Bool`). And then another one that returns metadata about the session. Presumably that second endpoint returns a 404 if the endpoint doesn't exist. So why have the first? It also doesn't conform very well to the idea of thinking in term of resources. The session *is* the resource. By default we should probably follow normal conventions:\r\n\r\n```\r\n/resource [POST]\r\n/resource/:id [GET, PUT, DELETE]\r\n```\r\n\r\n# How do we deal with duplication?\r\n\r\nThere's starting to be some duplication in functionality (with very different code paths) between the servant and snap servers. This seems bad. How do we deal with?\r\n\r\n# How should we represent sum types?\r\n\r\nOne suggestion was to add an extra `type` field.\r\n\r\n# What endpoints do we actually need? \r\n\r\nIf we're redesigning, it'd be important to know what we need and what we don't. Does there need to be an endpoint for deleting session tokens? If a frontend wants to end a session, should it just not send the session token instead? It'd be nice to be concrete about this. E.g.:\r\n\r\n```\r\nCRUD user\r\nCRUD service\r\nPOST/GET service/:servicename/session\r\n```\r\n"},"comment":{"url":"https://api.github.com/repos/liqd/thentos/issues/comments/145809524","html_url":"https://github.com/liqd/thentos/issues/330#issuecomment-145809524","issue_url":"https://api.github.com/repos/liqd/thentos/issues/330","id":145809524,"user":{"login":"ChristianSi","id":4480899,"avatar_url":"https://avatars.githubusercontent.com/u/4480899?v=3","gravatar_id":"","url":"https://api.github.com/users/ChristianSi","html_url":"https://github.com/ChristianSi","followers_url":"https://api.github.com/users/ChristianSi/followers","following_url":"https://api.github.com/users/ChristianSi/following{/other_user}","gists_url":"https://api.github.com/users/ChristianSi/gists{/gist_id}","starred_url":"https://api.github.com/users/ChristianSi/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ChristianSi/subscriptions","organizations_url":"https://api.github.com/users/ChristianSi/orgs","repos_url":"https://api.github.com/users/ChristianSi/repos","events_url":"https://api.github.com/users/ChristianSi/events{/privacy}","received_events_url":"https://api.github.com/users/ChristianSi/received_events","type":"User","site_admin":false},"created_at":"2015-10-06T10:05:35Z","updated_at":"2015-10-06T10:05:35Z","body":"My viewpoints on some of this stuff:\r\n\r\n> We have an endpoint to retrieve user email. Another one to retrieve user name. Why do we split those up, rather than have a single endpoint that returns an object with both?\r\n\r\nYes, single endpoint. Like you said later:\r\n\r\n    CRUD user\r\n    CRUD service\r\n\r\n> There are also endpoints that return whether a session exists (a Bool). And then another one that returns metadata about the session.\r\n\r\nI'd suspect that we can (and should) simple delete this stuff.\r\n\r\n> What should POST return?\r\n\r\nRandom Google result from [Best Practices for Designing a Pragmatic RESTful API](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#useful-post-responses):\r\n\r\n> A PUT, POST or PATCH call may make modifications to fields of the underlying resource that weren't part of the provided parameters (for example: created_at or updated_at timestamps). To prevent an API consumer from having to hit the API again for an updated representation, have the API return the updated (or created) representation as part of the response.\r\n>\r\n> In case of a POST that resulted in a creation, use a HTTP 201 status code and include a Location header that points to the URL of the new resource.\r\n\r\nThat sounds pretty reasonable."}}