Support for scopes

[gjtorikian]

Many RESTful APIs support scopes for calls. In other words, you can't make a certain request or perform an action unless a client has been granted a certain scope. For example, using the "Gist Fox API,", you might need gist_write access to Edit a Gist.

Is there any support planned for surfacing this sort of information?

[zdne]

@gjtorikian

Support for authentication scopes is surely part of the dedicated authentication support - #11

I have started working on the extended version of the "Gist Fox API" that should demonstrate possible authentication in the current state of API Blueprint. You can check the work in progress here: https://github.com/apiaryio/api-blueprint/blob/1A/examples/Gist%20Fox%20API%20%2B%20Auth.md

Will this suffice to your needs? Is there anything in particular you would like to see in API Blueprint in regards of the auth scopes?

[gjtorikian]

That looks good to me! Feel free to close this out.

[zdne]

Awesome! Just poke me or write over here if you have any further remarks.

Thanks.

[gjtorikian]

@zdne Hm, in thinking about it a little further, maybe my proposal is a little different.

Let's take this markup as an example:

### Star a Gist [PUT]
This action requries an `access_token` with `gist_write` scope. 

To define a textual scope, the header could change to

### Star a Gist [PUT] [gist_write]

Likewise, something similar for the other direct notation:

# PUT /gists/{id}/star [gist_write]

I think the proposal you have right now assumes that an auth_token is passed in within the body. That's great, but I'm actually more curious about surfacing the type of the auth_token within the doc (outside of the written description).

I use the brackets notation ([ ]) under the assumption that some calls might need multiple scopes.

If we can agree on a syntax, I don't mind putting in the work to implement this in Snow Crash.

[zdne]

@gjtorikian

Thanks for pounding into this issue! I will be happy to work together to address resolve it. I like the way your are thinking about it, providing essentially tags for resource. However I would like the solution to cover following.

1. Definition & discussion of authentication method(s) used throughout API
2. Definition & discussion of scopes if applicable
3. Definition & discussion of authentication options for a given Resource
4. Definition & discussion of scopes valid for a given Resource

With these goals on mind I am currently thinking about two possible takes:

1. Coming up with a dedicated syntax for 1. - 4. as Authentication #11 suggests

   OR

2. Use proposed "metadata" syntax – Support for Specific Metadata #38

The dedicated syntax has the advantage in parser could support it with meaningful warnings and perhaps better clarity in general. The metadata approach would just piggy back on another syntax reducing the time complexity of parser.

What do you think?

[zdne]

Also going the dedicated syntax way the AST and its serialization would have to be modified accordingly.

[rurounijones]

We have a slightly different issues regarding scopes. In our APIs the authentication scopes have a material effect on the response bodies (as well as the broader access allowed/denied bits). For instance

plebian scope would return an object with super_secret_field excluded
big_kahuna scope would return an object with super_secret_field included.

I do not see a way to easily do this at the moment using the current syntax. If we defined scopes as something referable somewhere then we could add information to the response object somehow?

However if we are also using JSON Schemas then we would want to assign specific responses to specific scopes.

it is almost as if scopes would be a sub-section inserted between the Action and the request, response, schemas etc.

[zdne]

@rurounijones

I understand your use-case however even if you would be able to specify an access_token with your request the scope type would be an out-of-band information. Tied with your token but not apparent from its value.

E.g. (pseudo blueprint):

# GET /1{?access_token}

+ Parameters
    + access_token ... oauth access token

+ Response 200

   { super_secret_field }

+ Response 200

   { no_super_secret_field }

My point here is, even if you would be able to do condition based on a parameter's value it would be no help because access_token value 1111222233334444555ABCDEF does not say anything on what scope it bears.

Ideas?

[rurounijones]

I was thinking of making it more free-form by allowing another section. (I did some checking and we also have scope specific request parameters, hence the duplication of basically everything.)

# GET /1{?access_token}

    + Scope BigKahuna

        Freeform text describing the details of BigKahuna scope

        + Parameters

        + Request

        + Response 200

               { super_secret_field }

    + Scope Plebian

        Freeform text describing the details of Plebian scope

        + Parameters

        + Request

        + Response 200

               { no_super_secret_field }

[zdne]

@rurounijones

Understood. But how it is different to just name a request a group it with relevant response? E.g.

+ Request With Token A

    ...

+ Response 200

    ...

+ Request With Token B

    ...

+ Response 200

    ...

Since there is no clear programatic way to check the token's scope (you would have to say take the token, go to this URI and check the field "scopes") it is really only about the human readable documentation

---

Thinking more and more about it we will probably need to semantically know that this is a scope for some possible future tools. What I am still struggling to imagine is what the tool would do with that information.

Let' say you want a tool that performs a request on certain endpoint with the scope X. Will the tool get a token at its input from "someone" who will say this is the token with the scope X. Or will the tool obtain the token with the scope X by itself? How?

Sorry if this is a mess I am pretty much brainstorming here..

[rurounijones]

To be honest, for us right now, your first option would suffice.

I would imagine future tools would require some sort or input method but that would be out of scope for API bluebprint, as long as there is a way to semantically identify the different scopes how the scope is input is down to the tool.

I know that some companies with interactive API documentation have an input box on their pages where you add your token before using the tool.

For something like automated testing based on the API Blueprint the testing tool could be able to automatically fill in the required token based on naming rules.

[zdne]

@rurounijones

Not sure what you refer to with first option. If it is the blueprint code in my previous comment you can do it already today. Refer to identifier in Action Request Section. It might be however that it is not properly rendered in Apiary for the time being (working on it!).

[rurounijones]

@zdne Yes, I started using the first option and that will do for the moment, the points you brought up regarding semantic meaning for the scopes for future tools is also a valid thing to think about and I do not think it should be forgotten.

I just wanted to say that, at the moment, we are using your first suggestion.

[zdne]

The #47 Traits proposal should address both the need of reusing any mechanism needed for authentication as well as add the possibility to add semantics (tag) to any request / response.

[zdne]

To be addressed (and closed) with #47.

[zdne]

Closing as duplicate to #11.

See (and comment on) RFCs #11 (comment)