I'm a new to RESTful API's and sort of developing my first one at the moment for a mobile application to be followed. I have a question regarding API versions and how to manage/tackle them.
At this moment, my API 'version' is a directory named v<version_name> in which my API class resides. In that directory, I have resources that the API and REST client needs in another directory named include. So the structure is as follows: example.com/api/v0.2/method_name/ and on .htaccess, I'm making sure that everything that follows the API version (hardcoded in the .htaccess file, is saved in a query string parameter).
I'm not sure if it is the right approach for a live application as it requires manually changing the URL endpoints at clients' ends, too. So my questions are:
Is this the right approach to API versioning?
If it is and I keep it, how do I deal with outdated URL's. Say for instance the app is live and I update the API to v0.3 but the client who have the app installed would be accessing v0.2 and getting a 404 response code back?
Is there more elegant solution out there? It must be.
Edit: there are some resources that reside outside of the api folder itself, in the root include folder so to speak.
Edit 2: My API is targeted to be consumed by mobile applications and is not publicly consumable.
While I think these questions are primarily opinion-based, I will have a go...
I think it is a valid approach, and I've seen others use it,
including Microsoft.
When it is necessary to outdate an API, you could give a 404
back with an explanation that the new API is at the new address.
HOWEVER it is usually a bad idea to just retire an API version; you
would at least have to give client developers enough time to switch
to the new API before retiring the old, if at all.
A more elegant solution would be to just keep the API at one
address, and update that as necessary, and add to it rather than
replace whenever possible. Keep supporting outdated functions for as
long as possible and have open communication to client developers
about when a certain method will no longer work.
Just my opinion, do with it what you will...
Related
I have undertaking a master thesis project that uses the openapi.yaml files to auto generate test for REST-api web-services - This has lead me to host a local instance of gitlab, so that I can run the tool I am working on, on gitlab. For that to happen I need the .yaml files containing the documentation for the API calls. Such files are found within in the gitlab source-code, but the call does not seem to work.
Some calls work, namely:
http://localhost/api/v4/version
http://localhost/api/v4/users
http://localhost/api/v4/projects
http://localhost/api/v4/groups
all returns meaningful JSON.
the problem is that a lot of the calls within the documentation does not work (returns a "404 not found"), namely:
http://localhost/api/v4/metadata
http://localhost/api/v4/projects/{id}/access_tokens
and more calls specified in the documentation.
The problem is that a lot of the calls that work are not documented (all of the above except the 'version' call). I have really tried to look for an alternative openapi.yaml files, but with little success and I am also puzzled to why the one left in the actual source-code does not contain meaningful documentation. Have I overlooked something? I am currently using postman and providing a sudo authentication-token.
Thanks in advance - I must surely have overlooked something!
Currently I have tried to look for an alternative openapi.yaml both by googling and be browsing swaggerhub.com. I Have look at the documentation pages for gitlab, but I have not found anything I did not already have.
Unfortunately, at this time of writing, GitLab does not provide an OpenAPI spec for all of its API. Only a very small part of the API is documented in openapi.yml. There is an open issue that is tracking this improvement.
For now, the online API docs are going to be your best source of information available on using the GitLab API.
As for your problem of getting 404 responses, the most common cause of this is that the credentials you are using do not have permissions to the project/feature you are trying to access or you are not using a proper authentication method. Also keep in mind some features of the API require an appropriate license entitlement.
I've been looking at backends and APIs for a while now. It seems that sometimes devs will build a regular backend (in say a language like PHP) that handles all the backend matters and sometimes devs will instead choose to build out their backend through an API and then use their own (and possibly other) sites to pull data from this API.
I was wondering this:
Say I want to build a regular backend using a server-scripting language like PHP, which I will use to not only render my main website, but will also allow me to do other server-side scripting etc. Then say I want to use this data from the current site and make it accessible to another site of mine through API calls. Will it be possible to build an API on top of a regular backend?
If the answer yes, how complex can it get to achieve something like this?
What tools or design strategies (if any) would you have or have used for achieving this?
This is an old question, but since I'm here, I may as well provide an answer for anyone wondering. Joe is asking about server-side web APIs versus regular server-side code.
Yes, you can have a "regular" backend and an API backend exist at the same time. If your backend is in PHP, you can refactor and extend your code to handle API requests.
Like Patrick Evans said, an API is the backend. If your backend PHP code communicates with a database to manipulate or retrieve data, then you can consider this an API transaction. Whenever your backend receives a request, evaluates/actions that request, and returns a response, it is essentially acting like an API.
Let's say you own example.com, with an index.php file in the root directory - so when a user requests example.com in their browser, this index.php file is processed and served to them. Now, you can set up this index.php file to handle both regular page requests (i.e. the php script returns an html template that is rendered by the browser) and API calls. This can be as complex or as simple as you want it to be.
The best way to handle this would be to assign different routes for rendering your main webpages and API calls. You can set up routes in the following way...
example.com/index.php?route=api&data=users can be handled by your 'API code' in index.php to return a JSON response containing a list of all the users in your database, while example.com/index.php?route=home will just return your website's home page.
The webapp I'm making is medium-sized, and it's going to be a single-page static JS+HTML app (made with Backbone, and served by nginx) which accesses an API, hosted on a proper webserver.
Should the API be under a different hostname, or same hostname but different path? What could be possible pros & cons of these options? Both options are feasible, thanks to nginx.
I would suggest using an intuitive separated environment. Splitting the access location like example.com and api.example.com allow the hostnames to describe the purpose of each environment. Separating these keeps things organised and clear while using the same hostname for each could cause confusion as to what kind of request is being done.
Using example.com/api is possible as well, but could lead to future issues where directories are used for other things as well. E.g., would example.com/newfeature have a directory like example.com/newfeature/api as well?
In the end, it's all a matter of personal preference though. Pick something that works in a clear way for your environment.
I think your question is somewhat irrelevant, as long as your code is flexible about the base url of the api. Make sure you can configure your code (both javascript and back-end) so that all api URLs are relative to some single configuration parameter and you will have flexibility to put your api service anywhere you want or need to put it.
I tend to think it might be a good idea to have everything on the same hostname, because the user might have disabled 3rd party cookies, and so the API server won't be able to recognize you after you close your browser. Before anyone tells me I should have the main website serve the cookies instead, let me tell you that I'd like the main website to be completely static HTML/JS files, and so they have no ability to serve httpOnly cookies, which is the kind of cookies I like.
Hi I have created a package for my metro application.Here while developing my app I have given a Url static,But I need to change Url dynamically whenever my requirement changes.So that what should I do?Can anyone help me.
Thank you.
If your requirements are changing, then you might be releasing a new version of your application anyways, so it might make sense to just update your app package manually each time the URL changes and re-release it. This is definitely the simplest solution if your URL is going to change infrequently. You would also need to handle deprecating the old URL in this instance or at least gracefully handling when the old URL is shut down so that users who have not upgraded to your latest version still don't have a horrid experience.
If that is not a viable option, then it gets a bit messier from here on. Really the only way to change the stored URL would be to have some sort of secondary service or authority on what the current URL is. The app would then do one of the following (or a combination):
Query the URL authority for the current URL before making any requests.
Attempt to make the request to the current stored URL, if it fails, query the URL authority for the new URL and store that URL.
Currently Azure Websites don't allow custom SSL certificates, but they have wildcard SSL enabled for the *.azurewebsites.net domain. I need a secure login form for my web app, but with no custom SSL, it appears that I'm SOL.
Is there any kind of workaround for this? Would it be possible somehow to have a login form at https://mydomain.azurewebsites.net that creates a forms authentication ticket that will then work at http://mydomain.com?
Couple of months ago I had exactly the same problem i.e. application was built on Azure Websites, had to run on custom domain other than *.azurewebsites.net and had to allow secure login process.
Workaround for that we used was to embed an iframe (using secure protocol and .azurewebsites.net domain name e.g. https://oursite.azurewebsites.net/login) into non-secure page on custom domain (e.g. http://mysite.com/login). And entire login process was performed in the iframe.
There is one thing which you should be aware of, namely, lots of customers checks whether the page where they provide their credentials was using secure connection or not. In our case, secure iframe in non-secure page was causing lots of customer complains. Workaround for that problem was to put a message confirming that the login process uses secure connection. The message made some improvements, however, still certain number of customers complains remained.
I hope that will help.
This isn't really an answer to your question, but Microsoft are very aware that custom mapped SSL to websites is one of the most requested features for Azure websites and they have said they are working on it.
Scott Hanselman himself confirms it here
In the meantime, Tom's answer is a perfectly valid workaround.
One thing I would be very wary of though is with something Tom brings up: the security warning that the browser will present. You'd be amazed how many people freak out when they see that message and don't go any further! We have a fairly active ecommerce site and there have been occasions where we have accidentally used a none secure image path on an SSL page and we have always received emails from customers asking if our site has been hacked or similar!
The disclaimer that Tom mentions is a good idea, but I think it will still put some people off.
I am working directly with the WAWS team right now to produce some public guidance for this. A GitHub repository with the requirements is currently being evaluated by the team (I sent it over to them literally 1 hour ago). Hopefully, the solution will be approved and made public within a few weeks.
I can say this - the workaround won't be fully supported or much custom guidance given on its usage aside from the repository and accompanying documentation. SSL is, literally, the #1 priority for the product, and hundreds of people are working insane hours to make it happen for everyone. This workaround should also be considered temporary, as you'll no longer need it once the full SSL functionality is launched.