testing in local environment (Win7, XAMPP , WAMP)

[ktwist]

I am trying to install this api on local machine for testing purpose, but only thing i can get is the first level of links. (url with /api/ on the end). Other links (joomla:articles, joomla:weblinks, etc.) gives me "403 Forbidden, You don't have permission to access". Windows 7 dev machine with XAMPP. Also tried WAMPP. It seems that ":" in links causing problems. Any help or hint or direction for solution is greatly appreciated.

Thank you

[frankmayer]

Hi, just stumbled upon the same issue. Is there a quick workaround for this?

[chrisdavenport]

The problem originates in the router, but I don't have a fix or workaround at the present time. Suggestions welcome.

[frankmayer]

@chrisdavenport

Actually it's an Apache "issue" when it runs on windows. It doesn't even get to the api/index.php in my case. I put a breakpoint, and it never got triggered...

... and Apache error log shows:

[core:error] [pid 12472:tid 1496] (20024)The given path is misformatted or contained invalid characters: [client 127.0.0.1:53923] AH00127: Cannot map GET /api/joomla:categories HTTP/1.1 to file

It looks like the colon is a problem, and should probably not be used, if it's not inter-operable.

I have gathered some links for you:

The Apache "issue": https://issues.apache.org/bugzilla/show_bug.cgi?id=41441

Some other stuff I quickly google'd:

http://www.webmasterworld.com/apache/4573261.htm

http://www.webmasterworld.com/apache/4062515.htm (don't use semicolons, too...)

[chrisdavenport]

Hmm. That's interesting and also a major pain. Thanks for researching it. Looks like we might have to rewrite the spec (and make the URLs less readable). Needs some further thinking.

[frankmayer]

Happy to have helped. :smile:

Just two thoughts on this matter.

I haven't followed the definition of the spec, but why not just stick with normal "paths"?

for example: /api/joomla/categories instead of /api/joomla:categories

The second thing coming to mind, is prefixes (mainly for reuse of the api by other components).

Prefixing would allow tiny little things like api versioning, etc...

For example: /api/somecomponent/v1/categories

What do you think ?

[frankmayer]

Hi Chris, are there any news on this issue?

[chrisdavenport]

I'm hoping to start working on a 3rd draft of the spec very soon. To give a quick answer to your question about why "joomla:categories" instead of just "categories": the "joomla:" prefix is a namespace (defined by a curie). Since Joomla is a generic CMS which can be extended by third-parties, there needs to be a mechanism to avoid resource name collisions.

[frankmayer]

Hi Chris, thanks for the update.

Explanation is fine.

But where I was going with my suggestion is, you can have the namespace without the colon. There is no need for the colon. It can be /api/joomla/categories instead of /api/joomla:categories

The example for my second proposal in the above comment would then of course look like this:

/api/joomla/somecomponent/v1/categories

[chrisdavenport]

Hi Frank,

I have now done some further reading on this issue and I'd like to offer my thoughts.

Firstly, it appears that colon characters in the path segment of URLs are perfectly legal [RFC3986](except as the first character in the path segment) and indeed are widely used (though presumably not on Windows servers!).

The problem appears to be that Windows is subjecting URL paths to the same restrictions that apply to its filesystem (eg. the NTFS filesystem considers a colon to be a special character used to denote alternative streams within a file). But resources referenced by the path segment of a URL are not necessarily equivalent to files in a filesystem. Most web servers will provide a mechanism that will map incoming URLs onto the services that will interpret them and that may or may not involve a full or partial mapping onto the native filesystem. For example, Apache uses an .htaccess file to map a URL such as http://www.domain.com/Welcome onto a file such as /var/www/index.php, which might be the entry point for a Joomla instance that will then use the URL path segment as a key to find and return the appropriate content. There is no file called /var/www/Welcome. So it appears that Microsoft (or Apache) are in error in applying filesystem restrictions to URL path segments that are not being mapped onto the filesystem itself.

However, given that Microsoft are highly unlikely to want to fix this particular bug, we need to find an appropriate way of dealing with it.

I'm guessing that percent-encoding the colons in the path segment isn't going to work as Apache on Windows will presumably decode them and still subject the URL path to the same filesystem restrictions.

Replacing the colon with a slash appears like a simple fix, but the problem is you'd have to be certain that the router could always unambiguously determine whether a particular slug is a namespace, a resource name or something else. That might be possible, but only if we can be certain that identifiers will always be numeric and that services will always comply with the published specification.

However, I think there is a much simpler workaround that will avoid the ambiguity. All we need to do is to make the colon an optional separator in the curies. For example, suppose you were to install a service extension from a third-party developer called Acme, which by default uses the "acme" namespace. Then by default we might have resource collections and link relations with names "acme:articles" and "joomla:articles". These are curies that will deserialise to distinct URIs and can therefore be used to disambiguate the resource collections. However, on hosts with the colon problem we could simply drop the colon and use link relations "acmearticles" and "joomlaarticles". These would deserialise to the same URIs as before and will still disambiguate the resource collections, but the namespace is now implicit in the name rather than being a curie prefix.

This would require a small change to the WSWG specification to drop the colon as a namespace separator and re-classify it as part of the namespace itself, but that's pretty trivial. And of course, any software built to the specification would need to allow the site builder to optionally drop the colon from any namespaces. Indeed, I would recommend that site builders be given the ability to set the resource name/link relations to any valid string they might want as a configuration variable. Validity rules would need to be specified, of course, and would need to be tighter than RFC5988 and the curie specification would allow, simply in order to guarantee valid and unambiguous API routes.

So in conclusion, since using a colon is visually and semantically appealing, allows us to use the full HAL and curie specifications and makes the router's task much simpler, I think my preference would be to retain the colon by default but ensure that there is a workaround for those platforms that can't handle it.

What do you think?

[frankmayer]

Hi Chris,

I see your points towards unambiguous API routes and I agree.

I have not had the chance to work with Curie's or HAL, yet. I have overflown some articles I found on the net, just to get an idea, so I am not the right guy to say anything pro or con on the matter. :smile:

Having said that, if Curie's make the usage of HAL easier/better, then that would be fine and I think your idea of including the colon in the namespace itself, would be the way to go. Of course taking into account said incompatibilities on Windows.

However, I think that Curies and HAL are kind of "another way to go". Its future is still unknown as with many good technologies. Maybe people will jump on the wagon or not, but I think it's not mainstream API right now.

I think the Joomla Rest API should also be able to function using "non-Curie" url's and not HAL.

My reasoning is simple: There are client-side frameworks, like for Example Ember.js which have data adapters for the "mainstream" way of doing things. Having to write up special Data-adapters to support Joomla's WSWG specification will surely slow down any developments in that area. And if I were to write some component where I'd like to use a specific client side framework like EmberJS, I would then probably not use Joomla's Rest API, which would of course defy the cause of a REST API for Joomla.

So, why not have both? It would certainly open up more doors...

Using "non-curie" Uri's could also work. It would require for the component to do some bindings for the Uri's in order for the router to be able to decompose a Uri correctly, but it could work.

For example, I could imagine something like this (non Joomla code):

Router:bind('acme/article/{id}', $AcmeArticleModel->get($id));

There would be no ambiguities in this scenario.

Since I am on an off on Joomla projects I am not fully versed with routing internals on Joomla, so I don't know if the code example makes sense in the way Joomla Routing and MVC works right now.

Do you think this is possible/ logical?

[chrisdavenport]

Hi Frank/Don,

You raise some interesting points and since my last message I've been thinking more about namespaces and why we even need them. Actually, I don't think we need them at all. They were a nice idea at the time, but they complicate things (not just because of the colon issue) and the problem they were intended to solve (third-party resource name collisions) can easily be solved by simply allowing site builders to decide for themselves the resource names that will be exposed via the API.

I've been trying to stick to "mainstream API" design as much as possible so I'm a bit surprised that you think I'm not. Curies are certainly mainstream since they are embedded in XML and people use them all the time, probably without realising it. With regard to message formats I'm not sure there is anything that could be considered "mainstream", beyond merely saying that XML and JSON are mainstream formats. HAL is fairly widely used, as are a number of others. HAL supports both XML and JSON so you can take your pick as to which one you use. But probably the most widely used format in use today is "roll your own", which doesn't really help much. I suppose it could be argued that hypermedia APIs are not yet mainstream, but it's perfectly possible to use HAL and totally ignore the hypermedia features.

Just to run with your example of using Ember, there is no reason that a HAL Data-adapter could not be written (I believe at least one already has been). From what I've read, Ember basically just does CRUD so it wouldn't be taking advantage of the hypermedia features anyway, but it should just work.

However, I agree that at the Framework/Platform level we should provide API support that is agnostic, perhaps bundling adapters for the most common "standards". But for the CMS it's harder to get anything done without picking one or other of the standards. It's a bit like the MooTools/jQuery/Prototype/etc issue. The Framework can be agnostic, but the CMS needs to pick one and go for it and hope they back a winner. That shouldn't exclude people who want to use alternatives, of course.

I think your router suggestion should work and I think that sort of approach should be supported at the Framework level so we have lots of flexibility in constructing routes. But I think when designing an API for the CMS it would be preferable to keep routes as simple as possible and as I've come to realise, namespaces aren't really necessary for the CMS, so maybe we should bake that capability into the Framework, but then not actually use it in the CMS.