Docs: embed API #8107

stsewd · 2021-04-14T22:26:53Z

Wasn't sure where to put the "Others APIs", think we all agreed these APIs are different from the ones we have in rtd.org/api/

stsewd · 2021-04-14T22:27:59Z

docs/embed-api.rst

+Usage
+-----
+
+Check our :doc:`/guides/embedding-content` guide to learn how to use the embed API in your projects.


I was tempted to move the content from this guide to this section...

I think it's fine to have this split. This page is the "raw" documentation of the API's endpoint and the other is a guide that shows some examples.

humitos

This is a good start!

humitos · 2021-05-27T13:12:49Z

docs/embed-api.rst

+Usage
+-----
+
+Check our :doc:`/guides/embedding-content` guide to learn how to use the embed API in your projects.


I think it's fine to have this split. This page is the "raw" documentation of the API's endpoint and the other is a guide that shows some examples.

humitos · 2021-05-27T13:13:56Z

docs/embed-api.rst

+Additionally, you can use the API with:
+
+- `sphinx-hoverxref`_: Sphinx extension
+
+.. _sphinx-hoverxref: https://sphinx-hoverxref.readthedocs.io


This probably can be removed from here since it's already mentioned in the guide linked above.

I think is still useful to link to users directly to the extension, so they don't need to click around to use the extension

IMHO, we are duplicating content here that we need to maintain. If any, I think we could improve the guide to make the extension more prominent.

we are duplicating content here that we need to maintain.

But this is just a link :) and the docs about the extension and how to use it should be on the extension itself, not on rtd.

humitos · 2021-05-27T13:15:29Z

docs/embed-api.rst

+The embed API is exposed from the domain where your docs are being served.
+This is ``https://docs.readthedocs.io/_/api/v2/embed`` for the ``docs`` project, for example.


The endpoint also works at https://readthedocs.org/api/v2/embed/. I'm not sure if we want all people using the endpoint from the documentation's domain. Why is that required?

So you can avoid CORS issues and use the cookies from the same domain in private projects.

Yeah, I think CORS should be open and less restrictive --which I don't think will be a problem. However, cookies are required for private documentation on commercial, tho.

humitos · 2021-05-27T13:19:09Z

docs/embed-api.rst

+If you are using :ref:`private versions <versions:privacy levels>`,
+users will only be allowed to get the embed content from projects they have permissions over.
+Authentication and authorization is done using the current session,
+or any of the valid :doc:`sharing methods </commercial/sharing>`.


It may be good to be explicit that the sharing methods are only useful for commercial.

There is note about that at the top of that page

docs/embed-api.rst

humitos · 2021-06-01T16:32:12Z

I was thinking if it does make sense to publish the documentation for the Embed APIv2 now that we are deprecating it and working on a new APIv3? I'm not sure if we want people to discover it at this point and start building new tools with it.

stsewd · 2021-06-01T23:56:07Z

I was thinking if it does make sense to publish the documentation for the Embed APIv2 now that we are deprecating it and working on a new APIv3? I'm not sure if we want people to discover it at this point and start building new tools with it.

I think people are already using the embed api, but not sure if they are using it without the client, or at least @ericholscher has a .com client using it.

ericholscher

This seems like useful work. I think we're gonna need to keep supporting v2 in some fashion for a long time, given the amount of users already using it via hoverxref. Since it's already documented, having it be better docs feels useful to me. Hopefully this structure will also give us a bit more ability to deprecate it over time.

I don't feel strongly here though, but dislike throwing away this work if it's useful. @humitos will let you make the decision tho, as you're on the redesign.

humitos

This seems like useful work.

The work is useful. However, I think we changed directions in the following 2 months after the PR was created and now, with the current direction decided, I think we shouldn't promote API v2 anymore. The less we promote it the easier will be to deprecate it.

I think we're gonna need to keep supporting v2 in some fashion for a long time, given the amount of users already using it via hoverxref.

This is true, but we are the ones that have control over that extension. Once APIv3 is implemented we can immediately make the change and release a new version of hoverxref --users will gradually upgrade to the new version and we will be closer to remove v2.

On the other hand, having new users implementing new tools using the v2 all around the internet will drastically increase the deprecation problems in my opinion. In that scenario, we need to migrate the users of our extension and also all the users of these new tools that we don't know who they are and we don't have a good way to contact them either.

I don't feel strongly here though, but dislike throwing away this work if it's useful. @humitos will let you make the decision tho, as you're on the redesign.

I'm sorry, but I vote to not publish this content under our public documentation. We should share a PDF with this document to any user already wanting to build something with it that we can contact later, and warn them about the current status so they can make the decision by themselves.

I hope this makes sense to you.

(I left some other comments related to this in the review itself).

humitos · 2021-06-08T11:34:31Z

docs/api/embed.rst

+Usage
+-----
+
+Check our :doc:`/guides/embedding-content` guide to learn how to use the embed API in your projects.
+You can also use the API with our `sphinx-hoverxref`_ Sphinx extension.
+
+.. _sphinx-hoverxref: https://sphinx-hoverxref.readthedocs.io


I'd like to remove this section because this document is about the raw API (similar to the regular APIv3 where we are not showing use cases). Let's keep consistency here.

If you want to cross-reference to our guide, you can use a note/tip with the first sentence linking to it. Besides, I wouldn't mention sphinx-hoverxref here since it's one of the topics the guide already talks about: we are duplicating content.

humitos · 2021-06-08T11:41:07Z

docs/api/embed.rst

+
+.. warning::
+
+   This API isn't stable yet, feel free to `open an issue`_ if you find any problems.


This warning shows my point here. We are documenting, and promoting its usage, for an API and on the same page we are telling users "don't use it because it's not stable". We are not planning to make it stable either. We are planning to deprecate and replace it with APIv3. So, I don't think why it would be useful to document it for more users to discover it?

If there is a current user wanting to use it, we should share this document privately with them, warning them it will be replaced in the medium term and they should keep that in mind.

Agreed. It seems like we will want this post once embed endpoints are available on apiv3.

docs/api/embed.rst

humitos · 2021-06-08T11:45:00Z

docs/api/index.rst

+There are some undocumented endpoints in our APIs that are for internal usage.
+These should not be used and could change at any time.


This paragraph reflects the current state of the Embed API better than the documentation proposed in this PR to me 😄

agjohnson

Agreed this seems like something we want once the embed endpoints are on apiv3. Seems like we can come back to this PR and update it however, instead of throwing away the work here?

agjohnson · 2021-06-09T22:03:17Z

docs/api/embed.rst

+
+.. warning::
+
+   This API isn't stable yet, feel free to `open an issue`_ if you find any problems.


Agreed. It seems like we will want this post once embed endpoints are available on apiv3.

agjohnson · 2021-06-09T22:09:05Z

docs/api/embed.rst

@@ -0,0 +1,135 @@
+Embed API


If we're waiting until embed endpoints are on APIv3, this should go with our other APIv3 endpoint docs at docs/api/v3.rst

docs/api/embed.rst

agjohnson · 2021-06-09T22:18:28Z

docs/api/embed.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are using :ref:`private versions <versions:privacy levels>`,
+users will only be allowed to get the embed content from projects they have permissions over.


This seems like it's maybe changing with CORS changes

Nope, this doesn't makes reference to external site, but to requests from the same site.

agjohnson · 2021-06-09T22:18:39Z

docs/api/embed.rst

+
+If you are using :ref:`private versions <versions:privacy levels>`,
+users will only be allowed to get the embed content from projects they have permissions over.
+Authentication and authorization is done using the current session,


Suggested change

Authentication and authorization is done using the current session,

Authentication and authorization are done using the current session,

humitos · 2021-06-14T08:24:32Z

OK. I'm closing this PR for now. We may come back to it once APIv3 is implemented to re-open and update it or take some content for a new document.

Docs: embed API

317c669

stsewd commented Apr 14, 2021

View reviewed changes

stsewd requested a review from a team April 14, 2021 22:28

astrojuanlu mentioned this pull request May 6, 2021

Embedding Content From Your Documentation, blog post readthedocs/blog#83

Closed

humitos reviewed May 27, 2021

View reviewed changes

stsewd added 3 commits May 27, 2021 12:47

Merge branch 'master' into docs-embed

3836330

Updates from review

f8fc729

Move to api/embed

bbc4504

ericholscher reviewed Jun 8, 2021

View reviewed changes

humitos requested changes Jun 8, 2021

View reviewed changes

agjohnson reviewed Jun 9, 2021

View reviewed changes

humitos closed this Jun 14, 2021

stsewd deleted the docs-embed branch June 14, 2021 14:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: embed API #8107

Docs: embed API #8107

stsewd commented Apr 14, 2021

stsewd Apr 14, 2021

humitos May 27, 2021

humitos left a comment

humitos May 27, 2021

humitos May 27, 2021

stsewd May 27, 2021

humitos May 31, 2021

stsewd May 31, 2021

humitos May 27, 2021

stsewd May 27, 2021

humitos May 31, 2021

humitos May 27, 2021

stsewd May 27, 2021

humitos commented Jun 1, 2021

stsewd commented Jun 1, 2021

ericholscher left a comment

humitos left a comment

humitos Jun 8, 2021

humitos Jun 8, 2021

agjohnson Jun 9, 2021

humitos Jun 8, 2021

agjohnson left a comment

agjohnson Jun 9, 2021

agjohnson Jun 9, 2021

agjohnson Jun 9, 2021

stsewd Jun 10, 2021

agjohnson Jun 9, 2021

humitos commented Jun 14, 2021

		The embed API is exposed from the domain where your docs are being served.
		This is ``https://docs.readthedocs.io/_/api/v2/embed`` for the ``docs`` project, for example.


		.. warning::

		This API isn't stable yet, feel free to `open an issue`_ if you find any problems.

		There are some undocumented endpoints in our APIs that are for internal usage.
		These should not be used and could change at any time.

	Authentication and authorization is done using the current session,
	Authentication and authorization are done using the current session,

Docs: embed API #8107

Docs: embed API #8107

Conversation

stsewd commented Apr 14, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos commented Jun 1, 2021

stsewd commented Jun 1, 2021

ericholscher left a comment

Choose a reason for hiding this comment

humitos left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agjohnson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos commented Jun 14, 2021