Let's say I have a subdomain that I use for my site's API: http://api.example.com/
All of the API's methods are accessible as URL segments such as http://api.example.com/some_method, so the root itself isn't used for anything.
Should it redirect to http://example.com/, redirect to a 404 page like Twitter, emit a basic response in the format of the API with a short message, or just have it send an empty response?
Are there any resources out there (articles, etc.) with any other possible suggestions?
I think that's up to you. In a RESTful API, the root would be the starting point for visitors to learn how to operate your system (HATEOAS). But since you talk about /some-method, you're probably not using the REST architectural style, so that's not applicable.
I would avoid the empty response. Maybe a short message pointing to documentation for the API? It really depends a lot on how the rest of your system is designed, so it's hard to give "correct" advice.
Related
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...
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.
So I finally got a link in my facebook post using the properties parameters. I thought I could put my url scheme in there. But unfortunately it says it isn't a valid url, which makes sense. So I searched again for another solution. But everyone seems to be talking about fb:// and not their own app url scheme.
So I created this thread, hope somebody can help me.
Try using bit.ly (or some other URL shortener).
The last time I tried, bit.ly accepted any URI schema and just did a redirect. I've successfully used this in the past to work around inputs that expected either an HTTP or HTTPS schema.
Additionally, similar logic could be done on your own server if you prefer. Simply share a link to your own server on Facebook, and have your server side script do a 301 to whatever App specific URI you have.
We have a CMS system that creates long URLs with many parameters. We would like to change the way they are presented, to make them more friendly.
Since we have many sites already built on this CMS, it's a little difficult to rewrite the CMS to create friendly urls (although it's a method we're considering, if no alternative is found), we we're looking for a method that when a user clicks on a long url, the url will change into a friendly one - in the browser - without using Response.Redirect().
In Wordpress such a method exists (I'm not sure whether it's done in code or in Apache), and I'm wondering if it could be done in ASP.NET 2.0 too.
Another thing to take into consideration is that the change between the urls has to be done by accessing the DB.
UPDATE: We're using IIS6
If you're using ii7 the easiest way to do this is to use the URL Rewrite Module According to that link you can
Define powerful rules to transform
complex URLs into simple and
consistent Web addresses
URL Rewrite allows Web administrators
to easily build powerful rules using
rewrite providers written in .NET,
regular expression pattern matching,
and wildcard mapping to examine
information in both URLs and other
HTTP headers and IIS server variables.
Rules can be written to generate URLs
that can be easier for users to
remember, simple for search engines to
index, and allow URLs to follow a
consistent and canonical host name
format. URL Rewrite further simplifies
the rule creation process with support
for content rewriting, rule templates,
rewrite maps, rule validation, and
import of existing mod_rewrite rules.
Otherwise you will have to use the techniques described by Andrew M or use Response.Redirect. In any case I'm fairly certain all of these methods result in a http 301 response. I mention this because its not clear why you don't want to do Response.Redirect. Is this a coding constraint?
Update
Since you're using IIS 6 you'll need to use another method for URL rewriting.
This Article from Scott Mitchell describes in detail how to do it.
Implementing URL Rewriting
URL rewriting can be implemented
either with ISAPI filters at the IIS
Web server level, or with either HTTP
modules or HTTP handlers at the
ASP.NET level. This article focuses on
implementing URL rewriting with
ASP.NET, so we won't be delving into
the specifics of implementing URL
rewriting with ISAPI filters. There
are, however, numerous third-party
ISAPI filters available for URL
rewriting, such as:
ISAPI Rewrite
IIS Rewrite
PageXChanger
And many others!
The article goes on to describe how to implement HTTP Modules or Handlers.
Peformance
A redirect response HTTP 301 usually only contains a small amount of data < 1K. So I would be surprised if it was noticeable.
For example the difference in the page load of these urls isn't noticible
"https://stackoverflow.com/q/4144940/119477"
"https://stackoverflow.com/questions/4144940/url-rewrite-without-redirect-in-asp-net"
(I have confirmed using ieHTTPHeaders that http 301 is what is used for the change in URL)
Page Rank
This is what google's webmaster central site has to say about 301.
If you need to change the URL of a
page as it is shown in search engine
results, we recommended that you use a
server-side 301 redirect. This is the
best way to ensure that users and
search engines are directed to the
correct page.
In response to extra comments, I think what you need to do is bite the bullet and modify the CMS to write the new links out into the pages. You've already said that you have normal URL rewriting which can translate the new URLs to old when they're incoming. If you were to also write out the new URLs in your markup then everything should simply work.
From an SEO point of view, if the pages your CMS produces have the old links, then that's what the search engines will see and index. There's nothing much you can do about that, javascript, redirect or otherwise. (although a permanent redirect would get you a little way there).
I also think that what you must have been seeing in Wordpres was probably a redirect. Without finding an example I can't be sure though. The thing to do would be to use Fiddler or another http debugger to see what happens when you follow one of these links.
For perfect SEO, once you've got the new URLs working outbound and inbound, what you'd want to do is decide that your new URLs are the definitive URLs. Make the old URLs do a redirect to the new URLs, and or use a canonical link tag back to the new URL from the old one.
I'm not certain what you're saying here, but basically a page the user is already reading contains an old, long, URL, and you'd like it to change to the new, short URL, dynamically on the client side, before the browser requests the page from the server?
The only way I think this coule be done would be to use Javascript to change the URL in response to onclick or document.ready, but it would be pointless. You'd need to know the new short url for the javascript to re-write to, and if you knew that, why not simply render that url into the link in the first place?
It sounds more like you want URL routing, as included in ASP.Net 4 and 3.5?
Standard URL rewriting modifies the incoming request object on the server, so the client browser submits the new URL, and the downstream page handlers see the old URL. I believe the routing things extend this concept to the outgoing response too, rewriting old urls in the response page into new URLs before they're sent to the client.
Scott Gu covers the subject here:
http://weblogs.asp.net/scottgu/archive/2009/10/13/url-routing-with-asp-net-4-web-forms-vs-2010-and-net-4-0-series.aspx
Scott Gu also has an older post on normal URL rewriting outlining several different ways to do it. Perhaps you could extend this concept by hooking into Application_PreSendRequestContent and manually modifying all the href values in the response stream, but I wouldn't fancy it myself.
http://weblogs.asp.net/scottgu/archive/2007/02/26/tip-trick-url-rewriting-with-asp-net.aspx