I'm using SAP Success factors API that i found:
I'm sending get request to this host https://user_name.successfactors.eu/sfapi/v1/soap12?wsdl with relevant credentials and i'm getting an XML but without the user version (something like b1808 (for august 2018).
Do you know how can i get this version?
Thanks a lot:)
First of all, SFAPI is deprecated or will be deprecated soon and I personally expect SFAPI to reach "end of life" within the next releases. But that is my personal opinion, officially SAP recommends using OData API but does not restrict using SFAPI: Page 8/9 for Deprecation Info
I am quite familiar with OData API and did not find any version information, I assume this also applies to SFAPI. The assumption relies on the information, that the APIs are always downward-compatible, this means you don't have to develop for a separate version, you could developt against the API no matter of the underlying version of the system.
If you really require to split according to the version of your system you could only separate by your system. This means if you have a two-tier environment, you need to know where you are requesting the API and develop against it. Furthermore systems differ from 3 to 8 weeks, 4 times in a year, but still they are compatible.
Maybe you could describe your goal a little bit in detail, then I might help to find a good solution.
Related
We have our API versioning strategy based on URL.
I have couple of scenarios to add new enpoints , where I could not find any strategical reference for this.
Scenario 1:
An existing API having endpoints varyingly ranging from versions v1 to v4. Few endpoints are upto V2, few are upto V3, and few at v4.
In this situation If I have to add a new endpoint, Should I begin the version for the new endpoint at V4? Is there any standards for it.
Scenario 2
This is the different scenario. one of the API GW spanned across multiple microservices, and the micro services are grouped by resources within the gateway. so a resource have a one on one mapping against a service.
Similarly different API versioning exists btw resources here. Few resources were upto V3 and few are up to v5. if a new endpoint is required to be added to a resource which is already upto v3, should we add a new endpoint in v3 or should we create a v5 version of resource to add that specific endpoint?
Any suggestions would be helpful.
You're unlikely find a standard way of doing things. The closest thing to a standard is what Fielding and the HTTP specifications say themselves. You should expect these questions to enlist many subjective opinions. Here's my bias opinion based on experience and a deep understanding of the specifications...
Conceptually, there's no real problem with adding new endpoints to an existing API. Where this might be problematic is if your API is public and with public documentation. Once an API version is released, it should be immutable so that clients can rely on it. If you're adding surface area to your API, then I would recommend you create a new version. If you're unsure what that version will shape up to be in totality, you can always start with a pre-release version; for example, 4.0-preview.1.
Your second question seems to ask whether you should have symmetrical versions. You can, but it's solely at your discretion. You indicated that you have microservices, so unless you are building out an API for an entire product or suite, it is more flexible to allow an API to evolve independently. This will organically result in heterogenous API versions over time. That shouldn't be a problem IMHO. The key to making that manageable is to define a sound versioning policy, such as N-2 supported versions.
You've already elected to version by URL segment, so there's no going back. Versioning this way leads to a spider web of different URLs when the versions are not symmetrical. This is just one of the many problems you may encounter. Hypermedia is almost all but impossible to achieve when versioning by URL unless the versions are symmetrical. Ultimately, versioning by URL segment is not RESTful, despite being popular, because it violates the Uniform Interface constraint. The URL path is the resource identifier. v3/order/42 and v4/order/42 are not different resources, they are different representations. In the same way, I can ask for order/42 as application/json or application/xml, but they are not different API versions, even though they look completely different over the wire.
As an example, if you retrieve v2/order/42 and it has a link to customer/42, but the Customer API supports 2.0 and 3.0, how do you know which link to provide? If the client only knows how to talk v3/customer/42 and you give them v2/customer/42, it might break them. Furthermore, what happens if the Customer API doesn't support 2.0 at all? The Order API has to incorrectly assume v2 is a valid or it has to be coupled into knowing which versions are supported; both of which are not good. In all cases, the server still doesn't know what the client really wants. It is the client's responsibility to tell the server what it wants. Every other method of versioning does not have this problem as the URLs are always consistent. Let's say you version by query string with api-version, another popular choice. If you provide a link to customer/42, the link is valid regardless of API version. It's the client's job to know and append ?api-version=<value> to indicate to the server how they want to query the resource. This is why Fielding says that media type negotiation is the only way to version an API. It's hard to argue with the G.O.A.T., but using the query string or another header doesn't explicitly violate any constraints, even if media type negotiation would be better.
I'm trying to confirm all the calls we currently make are supported in Gooddata's java sdk (https://github.com/gooddata/gooddata-java/) before we decide whether to update to use this.
I have confirmed all cases except 2 and am hoping that someone might be able to suggest how I might make these calls in the java SDK today.
list all users in a domain: (https://help.gooddata.com/display/API/API+Reference#/reference/users/manage-users-in-a-domain/list-all-users-in-a-domain)
assign a userfilter to a user (https://help.gooddata.com/display/API/API+Reference#/reference/data-and-object-permissions/assign-a-data-permission-to-a-user/assign-a-data-permission-to-a-user)
I just want to confirm these operations are not currently supported before I investigate effort to add them.
As far as I know, you are right and there is no built in support for GoodData domain (also called organisation) user handling (yet). On the other hand using "com.gooddata.sdk.service.httpcomponents" you can easily work with any GoodData API within your code.
In case you wouldn't be tied to strictly to Java - there is possibility to use bit more robust "Ruby SDK" - https://sdk.gooddata.com/gooddata-ruby-doc/docs/getting_started.html which natively contains user management
Another possibility is to shoot feature request directly into the repository (https://github.com/gooddata/gooddata-java/issues) - we will check that up and most likely add the support soon (or at least give you the estimate).
So, I stepped once at this problem. I had offered a website that used the SoundCloud API. Everything worked properly. Content was extracted from the JSON and placed in the layout of the website. However, I received an email one day from the owner of the website, which indicated that the website did not work properly. I then came out to investigate and came to the conclusion that the "problem" was not on my side, but at SoundCloud's side. I studied on the API page of SoundCloud and came to the conclusion that the API had received a major update, making the link with SC and the site no longer worked.
Lately I'm trying many new APIs to, including those from Instagram and Dribbble. I was therefore wondering if it is at all possible to ensure that such problems can be reduced in the future or it might be appropriate API pages of this third-party APIs to monitor?
There's no "right" answer. After many years of using and maintaining many APIs here are some of the conclusions I've come to:
The best providers let you work with a specific version of their API whose interface and expected behavior never changes. They might release bug fixes and new endpoints, but you can be confident that as long as the API is supported it will not break your system.
A good provider will provide an end-of-life date for each version of their API. It's up to you to keep track of when you need to update.
Paid services will often be supported longer than free services. Plus the contract / SLA will guarantee it remains available for a specific amount of time.
The most popular APIs often have mailing lists and/or blogs. For those that offer it, sign up to be notified of updates. For those that don't you'll have to monitor their blogs or news posts. And I suggest not using any service that would drop support for an API version without warning.
is there an api call to get the latest version of the api?
something like:
https://rally1.rallydev.com/slm/webservice/versions
i have read through the documentation at:
https://rally1.rallydev.com/slm/doc/webservice/
but have not spotted anything like this.
all the urls have the version embedded in them, so it's like a chicken and egg thing.
Current version of API cannot be determined programmatically.
In WS API 1.18 we deprecated "current" pointer to the most recent version of the web service.It changed with every new release of the web service. We deprecated it because it was found to negate the benefits of the web service versioning. Users tended to point at current as a convenience without being prepared for its intrinsic volatility. To encourage users to point their applications at a specific version and to minimize the impact of releasing new versions of web service API we removed the current pointer altogether.
The most reliable way to check the latest version of API is to access our WS API doc you mentioned in your post.
There you can see the latest version under the Available Versions section in the left frame. The latest one is by default listed as selected.
I have a logistical question: I'm trying to figure out the best way to manage APIs getting out of sync with an app. The best way to explain it is with an example:
Let's say MyApp Version 1.0 posts to a "submit_feedbacK" API that requires first_name, last_name, and email.
I then submit MyApp Version 2.0 to the App Store. That version is designed to post first_name, last_name, gender, and email to the API. All of these are required fields on the API.
The problem I have:
- If I update the API before the new App is live, it will break Version 1.0
- If I wait until Version 2.0 is live and remotely cripple 1.0, I have to time it correctly.
I'm going to guess that the 'right answer' is to maintain two different APIs. But if both APIs post to the same live database, that makes things a bit awkward.
Does anyone have suggestions on how to model this?
This question may share some aspects with iOS consuming API design.
The right answer is definately to provide two APIs (at least for a short period of time while users adjust). You do not have to maintain two versions at the same time, as once a newer version is released you can maintain that one, and simply provide the old one for legacy users. The only real changes you may have to make to it are things like security patches or major issues. Major changes (such as you deciding to restructure your entire database) may lead to the old version not working any more, however update to newer API versions should be designed to allow previous versions to still function.
The other question I linked you to gives an answer about how you can have different version of your app access the correct version of the API.
Another note is that it may be easier for you (depending on what framework you're using) to design your APIs as engines or subapps, and simply mount them at different end points. I know that this is easily do-able in Rails by using Engines, and in Node with Express using app.use() with sub-applications.
I would use a webservice/http endpoint for the communcation with your app. If you preferer to maintain the same URL in all versions of the app, then include a version number in all the requests/posts to the server so it knows how to handle them. This will also make the development and tests easier as new versions can test against the new api on the server.
So on any function you can call in the webservice/server add a single variable with version number. a BYTE ought to be enough as I think you could start over and "kill support for v1.0" once you hit 256 versions of the same function (if ever).
Once the server receives a request/post with data, you can just code a simple switch/case structure in the server API so support works for both versions.
If they do similar, but eg. swaps the parametres or something, you can handle all these serverside and the BAL/DAL (n-tier structure) can be maintained on the server part of the solution.
Btw. my answer is not just for iOS or smartdevices, but merly a client/server approach for a "work-in-progress" production setup where everything has to be online, while still being under development and maintanance.
Hope it makes sense, otherwise, comment on it and I shall try to explain it further.
just FYI, I use CodeIgniter. I'm using the REST Controller provided at https://github.com/philsturgeon/codeigniter-restserver. I ultimated ended up settling on having different end-points for every version. Basically I'd check out a new repository for each release and put it into a unique directory. (i.e. http://www.mysite.com/1.0/api/method, http://www.mysite.com/1.1/api/method, etc) Trying to maintain multiple versions of an API under one code-base just sounded too scary. At least when I released a version, I would know it is locked in stone and I don't have to worry about breaking it. (Note: I had to use a special .htaccess tweak to get multiple CodeIgniter instances running from the same domain. I can share it if you like)