{"action":"created","issue":{"url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/201","labels_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/201/labels{/name}","comments_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/201/comments","events_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/201/events","html_url":"https://github.com/apiaryio/api-blueprint/pull/201","id":83501230,"number":201,"title":"Authentication syntax proposal","user":{"login":"pksunkara","id":174703,"avatar_url":"https://avatars.githubusercontent.com/u/174703?v=3","gravatar_id":"","url":"https://api.github.com/users/pksunkara","html_url":"https://github.com/pksunkara","followers_url":"https://api.github.com/users/pksunkara/followers","following_url":"https://api.github.com/users/pksunkara/following{/other_user}","gists_url":"https://api.github.com/users/pksunkara/gists{/gist_id}","starred_url":"https://api.github.com/users/pksunkara/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pksunkara/subscriptions","organizations_url":"https://api.github.com/users/pksunkara/orgs","repos_url":"https://api.github.com/users/pksunkara/repos","events_url":"https://api.github.com/users/pksunkara/events{/privacy}","received_events_url":"https://api.github.com/users/pksunkara/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2015-06-01T13:37:58Z","updated_at":"2015-06-02T09:02:33Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/apiaryio/api-blueprint/pulls/201","html_url":"https://github.com/apiaryio/api-blueprint/pull/201","diff_url":"https://github.com/apiaryio/api-blueprint/pull/201.diff","patch_url":"https://github.com/apiaryio/api-blueprint/pull/201.patch"},"body":"This PR includes syntax proposal for Authentication support (#11) in API Blueprint. The syntax adds an `Authentication` section and an `Authentication Schemes` section to the blueprint using which the writer can define the authentication schemes supported by their API and which endpoints need which kind of authentication.\r\n\r\nFor now, an user can select authentication schemes from a list of schemes which are inherently supported by the API Blueprint. They are:\r\n\r\n* Basic Authentication Scheme\r\n* Oauth 2.0 Authentication Scheme\r\n* Bearer Authentication Scheme\r\n\r\nFor more information, read the spec and the Authentication example in `examples` folder."},"comment":{"url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/comments/107874971","html_url":"https://github.com/apiaryio/api-blueprint/pull/201#issuecomment-107874971","issue_url":"https://api.github.com/repos/apiaryio/api-blueprint/issues/201","id":107874971,"user":{"login":"pksunkara","id":174703,"avatar_url":"https://avatars.githubusercontent.com/u/174703?v=3","gravatar_id":"","url":"https://api.github.com/users/pksunkara","html_url":"https://github.com/pksunkara","followers_url":"https://api.github.com/users/pksunkara/followers","following_url":"https://api.github.com/users/pksunkara/following{/other_user}","gists_url":"https://api.github.com/users/pksunkara/gists{/gist_id}","starred_url":"https://api.github.com/users/pksunkara/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/pksunkara/subscriptions","organizations_url":"https://api.github.com/users/pksunkara/orgs","repos_url":"https://api.github.com/users/pksunkara/repos","events_url":"https://api.github.com/users/pksunkara/events{/privacy}","received_events_url":"https://api.github.com/users/pksunkara/received_events","type":"User","site_admin":false},"created_at":"2015-06-02T09:02:33Z","updated_at":"2015-06-02T09:02:33Z","body":"> I feel like we may need to add another base type which allows you to define headers/query params/etc with no built-in logic.\r\n\r\n> You can then easily make the bearer type using this generic base\r\n\r\nThat was my thought process too. Let me explain it.\r\n\r\nThe concept behind the current syntax proposal is that an API Blueprint writer can develop his own custom authentication methods using MSON (using some kinda function/lambda syntax). But since MSON is not yet that mature and this is only the first iteration (basic support) of authentication, I have decided to add only 3 `Base Auth Schemes`.\r\n\r\nIn background, all these 3 auth schemes are doing conceptually nothing but extending the headers and query params of the request. An example of Bearer Auth Scheme can be seen below. (Pay attention to the template kind of stuff).\r\n\r\n```\r\n## Bearer Auth Scheme (Auth Scheme)\r\n+ Headers\r\n    + Authorization: *keyword* *sample_token*\r\n```\r\n\r\nI haven't proposed the custom authentication schemes because I felt that we would not do justice for it with the current state of MSON (even if we disregard functions) and whatever we implement is going to be very volatile due to it. We do not want the users to start using it and turn out we need to change how it works.\r\n\r\nSo, I have decided to propose only the 3 authentication schemes (which will be defined in parser) and consider this the first iteration of authentication rollout. I would love to do the second iteration later where these schemes are actually written in API Blueprint and parser just parses it. But as I said, we need to give some time for it.\r\n\r\nPlease ask me if you don't understand something I said.\r\n"}}