0

I'm just getting started with Apiary and I can't tell if this is a limitation of the product or just me not understanding what to do.

I'm documenting an API which authenticates the user as part of every request. Sometimes the authentication is part of the path (a request for the user's profile would have the user id in the path), other times just as parameters (?user_id=1&auth=secret), and for POST requests, part of the incoming body as JSON.

Also, there are 3 methods of authentication in the app. You can log in with a Facebook UID, email address, or using the unique id of the device you're using. The result is something that looks like this:

##User [/user/{facebook_uid}{?access_token}, /user/{email}{?device_id}, /users/{device_auth_id}{?device_id}]

This works fine, and displays in the API as I'd expect:

enter image description here

But this introduces 2 issues:

1) If I wanted to add a set of parameters shared by all authentication methods, I would need to add it to all 3 like this:

## User [/user/{facebook_uid}{?access_token, extra_thing, this_too}, 
/user/{email}{?device_id, extra_thing, this_too}, 
/users/{device_auth_id}{?device_id, extra_thing, this_too}]

This seems a bit messy, it'd be much nicer to apply shared parameters at the end of the path array so they apply to all, something like this:

## User [/user/{facebook_uid}{?access_token}, /user/{email}{?device_id}, /users/{device_auth_id}{?device_id}]{&extra_thing, this_too}

But this doesn't work. Is there a way to do this? The documentation wasn't very helpful with more complicated stuff like this.

Also, would there be a way to create some kind of template which I could apply to all my methods? In the case where the authentication is part of the path its a bit unavoidable, but for other requests it would be nice to just do something like include: authentication and have it pull the unique_id/auth combo from a defined template somewhere.

Thanks!

Almad
  • 5,753
  • 7
  • 35
  • 53
JMRboosties
  • 15,500
  • 20
  • 76
  • 116

1 Answers1

1

First, there isn't really support for having a single model with multiple resource representations. It is an unusual thing to do and is actually good food for thought.

Second, using multiple URIs in [path segment] is probably going to confuse Apiary's mock server and make it unusable.

In my opinion, I'd split this into three models: Facebook User, E-mail User and Device User, with slightly different documentation (how are they created? Can you really create all of them through api? etc. etc.)

It also depends on how you want to document this. As path segments are not validated (it would be strange to have different resources based on the type of the arguments), you can just have (and I'd personally do just that)

## User [/user/{id}{?access_token, extra_thing, this_too}]

+ Parameters
    + id (required, string, `test@example.com`)...id of the user. Can be either user's e-mail, facebook id or device id from where user was created.

As for reusable parts, this is currently being implemented with authentication being part of that.

Almad
  • 5,753
  • 7
  • 35
  • 53
  • I see, that makes sense. It would be strange to have different resources based on the arguments like you said, so I think the example you provided at the bottom is the best way to go about doing it for now. I don't think we're the only ones with multiple URIs pointing to the same resource, it'd be nice if they supported that in the future (without breaking the server like you said). – JMRboosties Mar 25 '14 at 19:42
  • Well you can use [Resource Models](https://github.com/apiaryio/api-blueprint/blob/master/examples/8.%20Resource%20Model.md) for that, but it's slightly different use-case from what you've described (one model is there while you, in fact, have slightly different models). – Almad Mar 25 '14 at 21:33