{"action":"opened","issue":{"url":"https://api.github.com/repos/uber-hypermedia/specification/issues/24","labels_url":"https://api.github.com/repos/uber-hypermedia/specification/issues/24/labels{/name}","comments_url":"https://api.github.com/repos/uber-hypermedia/specification/issues/24/comments","events_url":"https://api.github.com/repos/uber-hypermedia/specification/issues/24/events","html_url":"https://github.com/uber-hypermedia/specification/issues/24","id":66438365,"number":24,"title":"Clarify \"best practice\" for documenting params in a URITemplate or a Model","user":{"login":"inadarei","id":30158,"avatar_url":"https://avatars.githubusercontent.com/u/30158?v=3","gravatar_id":"","url":"https://api.github.com/users/inadarei","html_url":"https://github.com/inadarei","followers_url":"https://api.github.com/users/inadarei/followers","following_url":"https://api.github.com/users/inadarei/following{/other_user}","gists_url":"https://api.github.com/users/inadarei/gists{/gist_id}","starred_url":"https://api.github.com/users/inadarei/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/inadarei/subscriptions","organizations_url":"https://api.github.com/users/inadarei/orgs","repos_url":"https://api.github.com/users/inadarei/repos","events_url":"https://api.github.com/users/inadarei/events{/privacy}","received_events_url":"https://api.github.com/users/inadarei/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":0,"created_at":"2015-04-05T13:31:43Z","updated_at":"2015-04-05T13:31:43Z","closed_at":null,"body":"Per #19 there are two ways or creating equivalent of HTML Forms in UBER:\r\n\r\n1. URITemplates with action=\"read\" is similar to HTML Form with method=GET\r\n2. Models with action=\"append\" is similar to HTML Forms with method=POST\r\n\r\nFor the applications that are user-facing, it is often useful the API to provide hints for construction of the user interface (e.g. actual rendered forms). Such hints may include:\r\n\r\n1. Labels for the parameter fields\r\n1. Help tips/long-ish field descriptions\r\n1. Input types: multi-select, single-line text, multi-line text etc.\r\n\r\nShould UBER provide any guidance for the best-practice of implementing such things? If, yes - what should it be?\r\n"}}