Allow GET Endpoint to be both secure and un-secure


#1

I have a GET endpoint of a particular resource that I am trying to model in RAML. If the GET endpoint (/api/products) is accessed by an unauthenticated (anonymous) request it should return a certain result set. If an authenticated request accesses the same GET endpoint (/api/products) it should be able to get a larger result set depending on the permissions and scope of the user authenticated.

How do I model this in RAML? Is the even best practice?


#2

Well… I havent yet familiarized myself with the RAML 1.0 addition of multiple response examples… but I do believe that is possible now. So I think the good news is it is possible now with RAML 1.0, I am just not sure exactly how you do it. I could be wrong… that could just be for examples only and no way to specify the response path based on the request headers/parameters… but it is indeed something I need to learn and use myself. Perhaps @christian_vogel might know.


#3

@justjacksonn @jessemiller or @christian_vogel, did you gain any more insights into how to model varying resource types based on something like the permission’s an API user has got?
I have a similar use case to this of @jessemiller (I think). The resources I would like to model contain certain fields only if the user has a certain role. Furthermore there would be access restrictions in place which render certain fields read-only again based on the API user’s role. An anonymous user would not have access to certain resources at all while some are read-only (with a limited set of data).

I could imagine something like types and union types to express at least the existence of different schemas for the resource data, but how to express the fact of authentication being present or not and authorization levels restricting field access?


#4

MH, this is very much behaviour-driven and obviously hard to document. Do you even want to document that behaviour. If yes, you might be able to use a combination of multiple examples and annotations to do that. For example:

#%RAML 1.0
title: Simple API
version: v1

types:
  Roles:
    type: array
    items:
      enum: [ UNAUTHORIZED, ADMIN, MARKETING ]

annotationTypes:
  roles: Roles
  access_permission:
    properties:
      roles: Roles
      description: string

/data:
  get:
    (access_permission):
      roles: [UNAUTHORIZED, ADMIN, MARKETING]
      description: all roles should have permissions to get data
    responses:
      200:
        body:
          application/json:
            examples:
              unauthorizedExample:
                (roles): [ UNAUTHORIZED ]
                value:
                  data:
                    name: Christian Vogel
              adminExample:
                (roles): [ ADMIN ]
                value:
                  data:
                    name: Christian Vogel
                    role: Admin
                    lastLogin: 04/05/2016
  post:
    (access_permission):
      roles: [ ADMIN ]
      description: only the admin has permission to post new data

That is an example on top of my mind. What do you think?


#5

This looks spot on Christian. Assuming this could actually be parsed correctly, it seems like it would provide what myself and others are I believe looking to do.