We have solution based product which expose the rest API and our product has quarterly releases. Also, we expose an API for all the functionality we do in UI, and it may by around 30 end point.
Current we are exposing the API as v1.0 for first release planned on this Month.
My Question regarding this API versioning are,
Do we need to increase an API version whenever there is new set of API released?
Do we need to support all old API in new version if new version get release?
Ex: We have AddUser API in v1.0, if we release AddUserWithoutEmail API in v2.0 then Do we need allow AddUser API in v2.0
I am aware that there is many Q&A available on this topic but I didn’t get what I am exactly looking for so I have created this one.
Related
I am looking for a complete online reference for iManage's latest API. On googling, can see references to iManage v2 documentation, but that seems to be bit old and where can I find latest API if at all there is one
The latest version which is constantly updated is available at https://help.imanage.com/hc/en-us/sections/360000214214-iManage-Work-REST-API-Documentation - you'll need a login to IManage's support site to access this though. If you don't have credentials you can raise a ticket with your support provider to get access.
If you have an on premises server that's licenced for the API, you'll find the documentation for that specific version at https://YOURSERVERNAME/api-docs/
iManage has 3 different versions of API's
COM API > This is a legacy classic api which is reaching EOL on Dec 2023. So it is not recommended any more.
REST API v1.0 > EOL already reached (Dec 2022)
If you're on-prem technically you can use REST API 1.0 till iManage Work 10.4.4 (but please validate) but you will not have any support from iManage in case of any issues
REST API 2.0 (also called iManage Universal API)
This is the latest version and going forward you need to use this version. And if I am not wrong this is supported from iManage Work 10.2.3.
You can find latest documentation at iManage Universal API 2.0
Or you can find your Work server specific documentation https://YOURSERVERNAME/api-docs/ (Provided you entered API license while installing iManage Work software)
Newbie to API consumption and wasted hours trying to consume a REST 2.0 API resource to find out that we are using 1.0 API. Want to avoid this mistake in the future and looking for ways to identify API version that’s consumable.
In this case it’s an on-prem bitbucket server. Been searching if there’s any default ways to identify an applications API version without success.
Is there a good and easy way to identify which api version an application is accessible by?
No, I don't believe there is a general way APIs commonly use to communicate their versions
I got the task to integrate the systems of our old shop to Shopware 6. So I have to deal with the Admin API. The documentation says:
The Admin API is designed in such a way that all entities of the
system can be read in the same way. Once an entity is registered in
the system, it can be written and read via API
https://developer.shopware.com/docs/guides/integrations-api/admin-api/reading-entities
How do those entities work? Is there a list/documentation of all default entities? Do I have to register the entities myself?
Shopware 6 API documentation sources
There is a public Shopware 6 API documentation (admin API and store API) available at
For Shopware >= 6.4: https://shopware.stoplight.io/
All versions: https://swagger.docs.fos.gg/
Local Documentation
Otherwise you can use the /api/v{version}/_info/swagger.html as pointed out by Valerii.
Be advised that starting from Shopware 6.4, the API version is no longer used in requests. So as per documentation you have to open something like
https://your-shop-url.invalid/api/_info/swagger.html
Make sure you have set
APP_ENV=dev
in your .env and use this only locally and not on a publicly accessible server.
The advantage of using the local documentation is, that you will also see endpoints which are introduced by additional extensions.
Reverse engineering instead of documentation
In addition you can always check the network tab of your browser when doing the intented action in the Shopware admin panel, and learn about the necessary requests.
You don't need to register "default" entities that are provided by Shopware core. But if you define your own custom entity you have to register it as a service. You can get a list of entities that are registered in the core using /api/v{version}/_info/swagger.html endpoint which generates swagger UI docs.
I have added Dropbox support to my apps a while ago and never touched the implementation since. It is still running fine. However, a few month ago Dropbox updated the way permissions are handled which may require code changed in my apps. As explained by Dropbox I have to check if my apps work with short-lived access tokens.
The Dropbox docs describe the necessary changes when using their API directly but I use different versions of their official SDK in my apps:
iOS: ObjectiveDropboxOfficial 3.1.2
macOS: ObjectiveDropboxOfficial 2.0.6
Android: dropbox-core-sdk 3.0.6
As said, I have not changed or updated the Dropbox code in my Apps for a while. Newer versions of the SDKs are available and I will update them soon. However, I am not sure how to test, if the existing versions of my apps, using these SDK version support short-lived access tokens or not. How can I test this?
I have only configured the SDK code (provided the API key, etc.) and all API calls, tokens, etc. are handled by the SDK. How do I find out, if these SDK version work correctly work with the updated API?
The official Dropbox SDKs have been updated to support short-lived access tokens, as of v5.0.2 for the Dropbox Objective-C SDK, and v3.1.0 for the Dropbox Java SDK.
You should update to the latest versions and then update your code to use the latest methods for the authorization flow as covered here for the Objective-C SDK and here for using the Java SDK in an Android app.
Once you've done so, you should test the full app authorization flow by signing out and signing back in again, in each version of the app, along with whatever other testing you would normally do.
I'm new to this api documentation era.
Vising this api documentation, I get to post and query data. I understand that's a demo api documentation with swagger.
But what happens with real world API documentation? do I have a documentation in demo.api.myawesome.com and actual api on api.myawesome. com using different data stores?
But again digging deeper, I got to find out that an api can be self documenting using swagger libraries. This seems like both api and documentation are using the same data store which can't be the case.
What am I missing here?
From the Swagger website:
Swagger is a set of rules (in other words, a specification) for a format describing REST APIs. The format is both machine-readable and human-readable. As a result, it can be used to share documentation among product managers, testers and developers, but can also be used by various tools to automate API-related processes.
So yes, it uses the same "back end" as the actual API. It's just visualizing it, allowing you to interact with it via the Swagger UI.
If you mean Swagger UI - the "try it out" button sends requests to the server specified by the host property in your spec. If host specifies your production server, requests will be sent to production; if it points to a sandbox, "try it out" will use the sandbox. You may have a version of the spec for internal use that points to production, and a public version that points to sandbox.
Note that Swagger supports authentication as a way to ensure that only authorized users (e.g. your actual customers with valid credentials or API keys) can make API calls.
You can omit host from the spec to disable the "try it out" functionality - this way you can still have the API docs, just without the interactive part.