Ive been making API's for about a year now and I was taught to use http://IPAddress:Port/api/v1 all the time when building an API with express.js. Is there a specific reason I would want to do that? Is this just denoting that the API is in development? Ive recently changed my API to not run on port 3000 so that I am able to just say http://IPAddress.com/ instead of http://IPAddress.com:3000/api/v1 and it works just fine the new way.
One main reason for versioning an API is because it may be that an API can be improved upon but doing so might lead to breaking changes (for example, it might not work for applications that are consuming the API because an endpoint has been modified).
So, the solution to this is to allow consumers of the current API (v1) to keep using it until they want to switch, and release an updated version (v2) for new consumers.
Here's some more info on it: https://restfulapi.net/versioning/
Related
I need to purge my users on an OpenStack project easily, through an API call.
Just like this CLI command :
neutron purge PROJECT_ID
Which is available in the Neutron project docs, but with an API call.
I couldn't find the API, so actually my question is :
1. Isn't there such an API?
if there is not,
2.why?
Is there a specific reason for?
I checked out the source-code of the clients and neutron-server, but unfortunately there is no dedicated endpoint in the REST-API for this functionality.
This feature is only supported by the neutron-client, but not by the openstack-client. When you run neutron purge PROJECT_ID all what the neutron-client does inside the python-code of the client, is to list all resources which are related to the given project and then iterate over this list and send a delete to the neutron REST-API for each single resource. So its only a simple automatism in the python-code of the client and not a specific endpoint on server-side.
See the specific function inside the code here: https://github.com/openstack/python-neutronclient/blob/master/neutronclient/neutron/v2_0/purge.py#L63
Based on my experience with openstack and its community, I think it was done like this, because it was easier to add new code only into the neutron-client. When this should have become a new endpoint, this feature had to be implemented in neutron, openstack-client and openstacksdk as well. Each repository has its own team. This purge-feature is so small, that it was not worth to persuade all 4 teams. The more components you try to update for one simple feature, the harder it is, because the one who wants to bring the feature upstream, is responsible to bring the teams of all required components together and when only one within the core-teams have a problem with your implementation, you have to start nearly at the beginning. So it can easily take over a year or two to bring a cross-component feature like a new endpoint upstream, when you are not part of the core-team by yourself. So to bring the feature only into the neutron-client is quite easy compared to a cross-project contribution.
This is at least the reason, why I would implement this feature only in neutron-client too, or only in the openstack-client if possible, instead of adding a new endpoint, when I would bring this feature upstream.
Overview:
We have a rails REST API app that's gonna be published soon together with client app (single page app written in JS) . We intent to deploy new stuff on almost daily basis. For now the API is only used by us internally.
Questions:
How to manage deployment because we deploy each app separately?
Should we always deploy them together? Should we raise API version for each deployed change?
How to reload JS app when new version of API is available?
Should we not change the API version but keep backwards compatibility in mind? So only add new keys in JSON responses, no renaming, no deletions, no changing of URLs, ...
Are there any best practices described somewhere about this particular problem?
It is considered a best practice to only version a RESTful API when making a breaking change.
I would strongly suggest not releasing the API to the public until it has stabilized more. As long as it is internal-facing only, the frequent changes won't be as big of a deal. Once your API goes public, you'll want to limit the number of breaking changes (new versions) as much as possible, so work with your best customers before your public release to make sure the API is adequate, and try to design it with backwards compatibility in mind.
You should only need to pair the releases if there's a breaking change on the API side. Pairing them or not may be a business decision ("It's easier for our customers to have one version number to worry about than two").
You might also consider resetting the version number at release time so that the public is given the stable API at version 1 instead of 18.
So. I have embarked on the journey of learning Laravel in the last couple of weeks, and am thoroughly enjoying it.
It has come time for a site redesign and I thought it was about time to tighten up some of our functionality, so I am making the switch from CodeIgniter to Laravel.
I was wondering whether it is worth starting off with a RESTful API layer in Laravel (easy enough to create) and use it as a base even for the web application. In the future we are likely to build a mobile app that will need to use the API. So:
Is it worth having the web application connect to the API
and what is the easiest way/s to make calls to the API without having to write a bazillion
lines for cURL everytime I want to make a request?
It is definitely worth it.
I am currently redesigning a messy PHP code for an established hosting company turning it into beautiful Laravel code. I already have a mobile app working with it - Laravel makes it easy to return JSON data with one line -
Response::json('OK', 200);
or
Response::eloquent(Auth::user());
or
$tasks = Task::all();
Response::eloquent($tasks);
You don't need to use CURL as far as I know.
You can make all requests with simple AJAX, jQuery would simplify that.
Also using some MVC JS framework would help you make the application code structure more elegant for the client side, and the advantage is that you can easily package that into PhoneGap when you are ready to have your API take some real testing.
Today I posted on my blog about a simple example that you can try to see if this approach is worth your time : http://maxoffsky.com/code-blog/login-to-laravel-web-application-from-phonegap-or-backbone/
Check it out and accept the answer if you think it's on the right track.
As always, your results may vary, but this is exactly what I'm going through at the moment. I'm migrating a large .Net site with this API architecture and I've decided to keep it for Laravel.
I personally decided for this because:
More scalable. I can setup api.domain.com and then add additional
boxes/vm/whatever as our traffic grows. In fact, you could load
balance just the api by "round robin" or multiple dns entries for
that domain.
Future proofing for new sites and apps. Sounds like you're in the
same situation. I can see an app or two being added in the next year
or so.
Lost cost. You'll already be laying out your controllers, so really
it can be just a matter of setting them to RESTful and making small
tweaks to accommodate.
To be fair, some counter points:
Possibly additional load time, from processing through the API, though this should be minimal.
Additional security items to consider if you'd like to lock things down to just your app.
Either way, welcome to Laravel!
and what is the easiest way/s to make calls to the API without having to write a bazillion lines for cURL everytime I want to make a request?
#Sneaksta try postman chrome extension for calling rest services. you can create forms in this extension and pass data from these forms to you Rest services
https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?utm_source=chrome-ntp-icon
Our application is a API based one wherein the frontend relies on REST API calls to the back end. This sometimes creates a problem wherein the frontend team can't move forward unless the backend API's have been implemented since they invariably progress at different speeds. Is there a way to set up a server so that the front-ent can work independently regardless of the backend status ?
I know this is a bit of an old post but I created a tool just for this purpose and I thought I should share it for anyone who stumbles across it.
It's called Interfake and you can find it at https://github.com/basicallydan/interfake. I frequently use it for prototyping APIs which haven't been built yet, in fact that is my main use of it. I hope that helps.
A common solution that we work with is as follows :
FE and BE contracts/APIs are agreed upon and the back end apis are mocked.
The BE rest APIs use a filter that we configured.
For all the apis that are ready, the filter redirects to the correct api and for all the apis that are mocked the filter redirects to the mock api.
So transparent to the FE team as the BE team is building and completing more apis, they just update the map that the filter looks and and automatically the back end apis get invoked as soon as the BE team is ready to open it up.
So the flow is as follows :
FE ->BE Rest API Server
|API Filter->(for apis updated in the map as complete)-->server/port with actual api
|------------->(for apis that are still being mocked) --> server/port with mock
Hope that helps.
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)