Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
"self" as an object identifier, for documentation purposes #668
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:
it would automatically go to:
And in the API, if logged in:
would provide the same result as:
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.
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.
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.
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.
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
I agree with not using a 301 and having it just return a full object.
@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
I really like that idea. Let's set up a full example org, net, ix, and have it go to those.