Peeringdb: "self" as an object identifier, for documentation purposes

Created on 22 Mar 2020 · 14Comments · Source: peeringdb/peeringdb

For consideration... A "self" object identifier that could be used in documentation and examples. Then we could have a doc on docs.peeringdb.com which is somewhat alive, or a presentation PDF. Ex, when I am logged in, if I click on:

https://www.peeringdb.com/org/self

it would automatically go to:

https://www.peeringdb.com/org/550
[Altopia]

And in the API, if logged in:

https://www.peeringdb.com/api/org/self

would provide the same result as:

https://www.peeringdb.com/api/org/550

No reason:

https://user:[email protected]/api/org/self

couldn't also work.

Writes (PUT/POST/PATCH) to self would fail, as this is not meant to be used for production, since it is inherently not explicit.

The profile page for a user could be where the "self" pointer is managed, dropdowns for each major object type the user is affiliated with. The default would be to go to the first (lowest numbered) object owned of a type.

Minor enhancement

Source

ccaputo

All 14 comments

+1, i.e. I like this proposal but would recommend using "0" instead of "self"

arnoldnipper on 23 Mar 2020

+1, i.e. I like this proposal but would recommend using "0" instead of "self"

I shared that idea with Grizz. He indicated that 0 is sometimes overloaded for other reasons, whereas "self" could be a precheck and leave the door open to do other words for special meanings.

ccaputo on 23 Mar 2020

Is the idea to return HTTP 301:

https://en.wikipedia.org/wiki/HTTP_301

Or just to return the same information as the canonical link?

I am in favor of a redirect, but uncertain about the other approach.

shane-kerr on 23 Mar 2020

@shane-kerr I guess a 301 does not make sense. Calling this URL involves magic behind. Or not?

arnoldnipper on 23 Mar 2020

I don't think a 301 redirect involves any magic, but probably 301 is incorrect since the redirect is dependent on which credentials you are using, so please ignore that suggestion. :joy:

I guess this proposal is okay, but it is kind of non-RESTful. I'm not sure how helpful it would be for documentation, since after following the first link everything would immediately be different depending on the user's configuration. If we don't already have a link to get your ID then we should add that... it adds a step and does require that users set their links appropriately... but maybe that's a good thing in the context of a tutorial?

I won't give this proposal a -1, but I am not convinced enough to give it a +1.

shane-kerr on 23 Mar 2020

IMO we should separate the API and UI work into two issues. I can see a use case for the UI, but I'm not quite sure why anyone using the API would need this feature.
+1 for adding this to www but not for api

mcmanuss8 on 23 Mar 2020

I think it should be for both, and www just uses the API, so it would be a bit wonky to add it separately in both places. It's mainly for documentation and examples, so having it for the API is great for people to start learning with curl https://peeringdb.com/org/self etc.

I agree with not using a 301 and having it just return a full object.

I guess this proposal is okay, but it is kind of non-RESTful. I'm not sure how helpful it would be for documentation, since after following the first link everything would immediately be different depending on the user's configuration. If we don't already have a link to get your ID then we should add that... it adds a step and does require that users set their links appropriately... but maybe that's a good thing in the context of a tutorial?

@shane-kerr I disagree that it's not RESTful and it wouldn't change after the first link. I said it was "insane" after Chris first told me about it, but have warmed up the idea quite a bit since then. It's simply adding a little syntatic sugar in so examples and docs can say curl https://peeringdb.com/org/self instead of saying curl https://peeringdb.com/org/$ORGID -- which may seem a bit silly, but I think it would help lower the cost of entry for people looking to leverage PDB for automation.

grizz on 23 Mar 2020

I said it was "insane" after Chris first told me about it, [...]

Sharing the credit for insanity a little :-) ... this idea was inspired by a neat suggestion from Arnold to enable docs on docs.peeringdb.com to be somewhat alive.

ccaputo on 23 Mar 2020

👍1

So if you're not logged in, what should the behavior be?

mcmanuss8 on 23 Mar 2020

So if you're not logged in, what should the behavior be?

I defer to you all re this. Suggestions? Same as trying to pull up an undefined object?

ccaputo on 23 Mar 2020

I defer to you all re this. Suggestions? Same as trying to pull up an undefined object?

Maybe we can add an example org. That brings up the question to also allow for that example org a private ASN.

arnoldnipper on 23 Mar 2020

👍1

I defer to you all re this. Suggestions? Same as trying to pull up an undefined object?

Maybe we can add an example org. That brings up the question to also allow for that example org a private ASN.

I really like that idea. Let's set up a full example org, net, ix, and have it go to those.

grizz on 23 Mar 2020

I really like that idea. Let's set up a full example org, net, ix, and have it go to those.

https://peeringdb.com/org/25554 ... feel free to request affiliation

arnoldnipper on 23 Mar 2020

Summary

Add "self" object identifier to API and views for GET requests
For a logged in user, going to https://www.peeringdb.com/{net | ix | org}/self will redirect to the corresponding url for the first object of that type affiliated with the user
For a unauthenticated user, /self goes to an example org, ix, or net
Users can manage the self list in their profile to choose which affiliated object self points to if they have multiple options. Default will be the entity with the lowest id.