Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

"self" as an object identifier, for documentation purposes #668

Open
ccaputo opened this issue Mar 22, 2020 · 13 comments
Open

"self" as an object identifier, for documentation purposes #668

ccaputo opened this issue Mar 22, 2020 · 13 comments
Assignees
Labels

Comments

@ccaputo
Copy link
Contributor

@ccaputo ccaputo commented Mar 22, 2020

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:pass@www.peeringdb.com/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.

@arnoldnipper arnoldnipper self-assigned this Mar 23, 2020
@arnoldnipper

This comment has been minimized.

Copy link
Contributor

@arnoldnipper arnoldnipper commented Mar 23, 2020

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

@ccaputo

This comment has been minimized.

Copy link
Contributor Author

@ccaputo ccaputo commented Mar 23, 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.

@shane-kerr

This comment has been minimized.

Copy link

@shane-kerr shane-kerr commented Mar 23, 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.

@arnoldnipper

This comment has been minimized.

Copy link
Contributor

@arnoldnipper arnoldnipper commented Mar 23, 2020

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

@shane-kerr

This comment has been minimized.

Copy link

@shane-kerr shane-kerr commented Mar 23, 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. 😂

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.

@mcmanuss8

This comment has been minimized.

Copy link
Contributor

@mcmanuss8 mcmanuss8 commented Mar 23, 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

@grizz

This comment has been minimized.

Copy link
Member

@grizz grizz commented Mar 23, 2020

+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 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.

@ccaputo

This comment has been minimized.

Copy link
Contributor Author

@ccaputo ccaputo commented Mar 23, 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.

@mcmanuss8

This comment has been minimized.

Copy link
Contributor

@mcmanuss8 mcmanuss8 commented Mar 23, 2020

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

@ccaputo

This comment has been minimized.

Copy link
Contributor Author

@ccaputo ccaputo commented Mar 23, 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?

@arnoldnipper

This comment has been minimized.

Copy link
Contributor

@arnoldnipper arnoldnipper commented Mar 23, 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.

@grizz

This comment has been minimized.

Copy link
Member

@grizz grizz commented Mar 23, 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.

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

@arnoldnipper

This comment has been minimized.

Copy link
Contributor

@arnoldnipper arnoldnipper commented Mar 23, 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.