Skip to content

docs: add full schema link #1415

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
Jan 23, 2025
Merged

docs: add full schema link #1415

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4d8fc33
docs: add full schema link
TC-MO Jan 17, 2025
154c429
adjust links
TC-MO Jan 22, 2025
752c5e8
Update apify-api/openapi/openapi.yaml
TC-MO Jan 23, 2025
f66b77a
fix build and lint
TC-MO Jan 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion apify-api/openapi/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@ info:
The Apify API (version 2) provides programmatic access to the [Apify
platform](https://docs.apify.com). The API is organized
around [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer)
HTTP endpoints.
HTTP endpoints.

You can check the complete OpenAPI schema [here](https://docs.apify.com/api/apify-api.yaml).
Copy link
Member

@jancurn jancurn Jan 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't it be better to link https://github.com/apify/apify-docs/tree/master/apify-api/openapi instead of this strange page? People can find more in that directory. Also, please let's add JSON version

Copy link
Member

@B4nan B4nan Jan 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's the very same content, compiled into one file. I believe this is what anyone would use if they want to work with our schema.

I will add the JSON version tomorrow, again, it will be a single file. We can surely link to the source files if that makes some sense (but I am not sold on that really, who does that, what would be the use case?).

Thoughts @netmilk?

Copy link
Member

@jancurn jancurn Jan 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh yeah, but still I think it's good to link the GitHub source code from which the actual API docs are generated. We do the same for all our docs pages. And who knows, maybe somebody will send a PR...

Copy link
Contributor

@netmilk netmilk Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The simplest convention in the OpenAPI community is is that the compiled openapi.yaml and openapi.json are in the root of the API URL space, serving as a single source of truth for the API itself. They are idelaly deployed together with the API service implementation and tested against it.

In our case:

https://api.apify.com/v2/openapi.json

If not possible, the proposed URL will do for now, because we don't do "API design first" and the openapi document is dependant on the API implementation, not vice versa. The openapi document will be discoverable through the link in the API Docs for now.

it's good to link the GitHub source code
People won't see the href= base URL unless they "copy as link it" and paste it somewhere. If we want to navigate people to the Docs Github repo to edit the openapi, we need to do a better job communicating the repo in the docs itself. Something along the lines of clickable source maps comes to my mind.

Relevant to this, there are more API discovery options to evaluate:
https://apisjson.org/
OAI/OpenAPI-Specification#1851
OAI/OpenAPI-Specification#724

Copy link
Member

@jancurn jancurn Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the convention, we should ideally do it that way.

But still, let's add those YAML/JSON links to the API docs text (so that you can find it by searching "openapi"), and also let's add that link also to the GitHub directory with the source code.

Let's not overcomplicate this, we're talking about 2 lines of text here

Copy link
Member

@B4nan B4nan Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we can have a redirect (or rewrite) from api.apify.com, but from the context of apify-docs repo I don't think we can do that.

Btw since you wanted the JSON variant too, I had to patch the plugin, so I could alter the Export label too. Do we really need this if I change the label to Download OpenAPI like this?

image

#1419

Copy link
Contributor Author

@TC-MO TC-MO Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes more sense to me than to have a button & separate link within prose

Copy link
Member

@B4nan B4nan Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Btw I also changed the URL (as agreed with Adam) to http://docs.apify.com/api/openapi.yaml and http://docs.apify.com/api/openapi.json in that PR, so if we want to keep it in the description, we'll have to adjust that.

Copy link
Contributor Author

@TC-MO TC-MO Jan 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've adjusted the description, it's now shown in a bullet list like this

image

but with the changed label on the button, it seems redundant.

Any thoughts on this @jancurn, @netmilk ?


All requests and responses (including errors) are encoded in
[JSON](http://www.json.org/) format with UTF-8 encoding,
Expand Down
Loading