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.
Related
When reverse engineering an API, is there an advantage to looking at the mobile app rather than the web client? Looking at tutorials online, it seems much more common to focus on the mobile app, and I'm curious why this is. One guess: APIs used by mobile apps can only be deprecated slowly, since people can have stale versions of the app on their phone for months. Are there other reasons to prefer reverse engineering the mobile API?
Your guess about mobile APIs being deprecated slowly is a valid one and most significant argument in favour of choosing mobile API over web API.
Basically developers make new versions of mobile API either with new endpoints or keep old endpoints which have slightly different behavior depending on request parameters.
Regardless of the way they pick you are basicaly safe to keep your code as long as resource is alive - possibility of API change is very small.
Web APIs can change dramatically overnight because clients get new front-end code simultaneously along with API changes, i.e. API got changed along with clients.
Also quite often Web APIs provide responses which contain ready to display HTML data which is hard to digest(parse properly) sometimes.
Also it is sometime easier to reverse engineer parts of java byte code (to see the logic behind token/clientID generation) albeit it being obfuscated than trying to get understanding of obfuscated and minified javascript code.
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/
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
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)
I'm working on a project which involves a website, and after that is done, mobile applications (most probably will be built using a cross-platform tool like Phonegap or Sencha).
The overall application is heavily data-driven, all of which will be stored in MySQL databases on our webserver. I know that I will be setting up a REST API as a service layer for the mobile applications, but what I'm not sure about it - Should I be using this API for the main website as well?
I need to know this before I can begin the project, because if I do intend to eat my own dogfood, then the API will be the first priority.
In case it matters - the API will never be exposed to third party developers.
Sure, why not? It means that you'll have only one entry-point to test and monitor, it follows the DRY principle, and it will encourage better API design if you consume it too.
Yes you should use the API for the website. It simplifies your codebase and encourages code reuse, since you only deal with one API and not two (REST + MySQL). Furthermore, it makes life easier on the developers (that includes you!), because there is only one set of API calls to keep in mind at once.
Also, in the future you may build your mobile apps with HTML (perhaps using PhoneGap, recently open-sourced and renamed to Cordova). If your website uses the REST API, you can more easily port the web code to HTML5 for mobile.
Nitpick: This isn't really a matter of eating your own dogfood. Dogfooding typically refers to using pre-release code from the perspective of a user rather than a developer, to make finding bugs easier.