search

speakeasy-api / product-resources

Submit product requests and check release notes.
0 stars 0 forks source link

Finding ApiID and APIversion was not easy #9

Open aabedraba opened 2 years ago

aabedraba commented 2 years ago

Hi, in the documentation it was somewhat hard to know what ApiID and versionID exactly refer to. It would be great to have a section that helps you know where to get these values.

aabedraba commented 2 years ago

Furthermore, not really sure what it means to create an API from the dashboard, if what is input in the code is going to be the generated ApiID.

For example: GIVEN I create an API through the dashboard, and I name it "first-api" and the input a version "0.1" GIVEN I then configure the SDK to be "api-first" and set version to be "0.2" THEN the result is that my first API is not used, and another API is created in speakeasy dashboard with the content that I configured the SDK with.

Perhaps there should be a way to have the SDK configuration and the dashboard one validated and synchronized 🤔

simplesagar commented 2 years ago

Hi @aabedraba Thanks for using Speakeasy !

Thanks for pointing that out - i'll update the docs now with a clear description for ApiId and versionID.

ApiID is Speakeasy's way of identifying a an API. Its our top level concept indicating how endpoints are grouped. Often with REST APIs this is by the top level resource. Eg: A user's API with top level resource /user could be named with ApiID=user. All requests captured from your API server will be captured under this top level grouping. In this example that would be all handlers for user such as GET/PUT/POST for /user/{userId} . You have the option of instantiating multiple instances of the SDK in the scenario you are running different APIs on the same server. Example here : https://github.com/speakeasy-api/speakeasy-typescript-sdk#express-1

VersionID is provided as an input parameter so that you can differentiate different versions of a single API. These will show up as different entries on our API dashboard. It also enables running multiple versions of the same API in production.

simplesagar commented 2 years ago

Furthermore, not really sure what it means to create an API from the dashboard, if what is input in the code is going to be the generated ApiID.

We give you the option of instantiating new APIs directly from the SDK but you can also do it on the dashboard through the "upload schema/Add new API" button. This allows you to upload a new OpenAPI schema and input a new ApiID for your API. This is optional given not all APIs have OpenAPI schemas. More on this here https://docs.speakeasyapi.dev/get-started/quickstart#4-optional-upload-an-api-schema .

You are right that there is no enforcement for the ApiID created in the dashboard and the SDK to be the same. We're looking to create validation for that process and would love to hear your thoughts on what would make sense for you.