We are building a small web application in Rails that will allow clients to interact via an HTTP POST API; a typical client being another app such as an HTML form or mobile app.
We are at the point of deciding on the API field names i.e. the POST paramater names. We are wondering if there is a particular naming convention we should go with? E.g. snake_case, camelCase etc.
Some examples:
OPTION 1
employee.address.line_1=value
OPTION 2
employee_address_line_1=value
OPTION 3
employeeAddressLine1=value
We understand that all three options are technically permissible in HTTP POST, but are there any technical pitfalls we could avoid by using one over the other? For example, should we avoid using dots "." in the field names due to the ubiquitous use of 'dot notation' within programming languages?
Any advice would be greatly appreciated.
It ultimately comes down to what you and your developers are most comfortable with. I personally use camelCase for all my variables, HTTP_POST or programming. I would stick with camelCase or snake_case, camelCase though is most popular.
Dot Notation is one of the worst forms for a naming convention, and you stated why. If you happen to use any language on the form that uses dot notation for functions or other object related tasks you can run into problems. EX: javascript - not a good example but most functions are dot notated.
Related
I am starting to dive into graphql, building my first API with Rails. I have tons of questions regarding standards and conventions.
For example, I noticed the gem graphql by default requires the fields to be passed in CammelCase, when actually when I used to build RESTful API in Rails I always received the arguments in snake_case.
So I was wondering, is CammelCase the convention for Graphql? Should I still use it in my API? All my tests would assert the responses are in snake case too, is that correct?
It's certainly up to you and your application, and some libraries will automatically convert to and from camelCase, but given the choice, the GraphQL Rules website highly recommended that you just commit to using camelCase for all GraphQL fields and arguments, then convert those to camel_case fields in Ruby where necessary.
From the GraphQL Rules website website:
Rules and recommendations mentioned here were the results of 3 years' experience of using GraphQL both on the frontend and backend sides. We also include the recommendations and experience of Caleb Meredith (PostGraphQL author, Facebook ex-employee) and Shopify engineers.
Naming rules
1.1. Use camelCase for GraphQL-fields and arguments.
1.2. Use UpperCamelCase for GraphQL-types.
1.3. Use CAPITALIZED_WITH_UNDERSCORES to name ENUM-types.
I wish a bit that I had followed these for some past projects, but hey, they are still running just fine though :), but there has been churn where occassonally we were faced with some inconsistencies and chose to convert some fields.
What is considered the best strategy for URLs of translated websites? Something I see happen frequently is:
http://example.com/english-slug.html
http://example.com/de/english-slug.html
http://example.com/fr/english-slug.html
This has the (minor) advantage that a user can manually switch to another language by modifying the URL. The disadvantage seems to be that the URL consists of a slug in the wrong language for every page not in the default language. That would cause a SEO penalty, I think.
The alternative would be to translate the slugs as well and optionally omit the language identifier as well:
http://example.com/english-slug.html
http://example.com/deutscher-slug.html
http://example.com/slug-francois.html
Some languages do not really lend themselves to be 'sluggified', such as Russian, Chinese and Arab. You'll end up with transliterations that make little sense.
I think you should use language tags and translated slugs:
http://example.com/en/hello-world
http://example.com/de/hallo-welt
Why language tags? To avoid collisions.
Sometimes you might want to have the same slug for different languages (for example, "team" in English as well as in German).
Why translated paths? For better usability.
Not all users understand the "default" language, and depending on its script, they might not even be able to type/remember/dictate the slug. (It doesn’t make sense in the first place to use human-readable slugs that only part of your users are able to understand.)
Yes, it would be a "(minor) advantage that a user can manually switch to another language by modifying the URL". But it’s unlikely that users or search engines would expect this to work (see my related answer on Webmasters). So you would gain little (URL hacking for advanced users) and lose much (bad usability for users using the non-default language).
That said, it would still be possible to enable this URL hacking feature in most cases: When users change the language tag de (in /de/hallo-welt) to en (/en/hallo-welt), you could check if it exists (if yes, show it), and if not, check if there exists a slug "hallo-welt" in any language, find its English translation and redirect to it (from /en/hallo-welt to /en/hello-world).
Another way is setting the language as a query string parameter, such as:
http://example.com/hello-world?hl=en
http://example.com/hallo-welt?hl=de
for example Google Flights web site uses this method.
The best solution, if you can afford it, is to send the document with the right name, that means, using the right word on each language.
Of course each document should be sent with the respective language setting on the headers.
For storing them, you can use folders and let the web server choose the right document according to the language preference; or you can use server side technology, like PHP, perl, etc to send the document and adjust the URL.
In any case, you have to have a default language to be sent when you don't have the requested language.
If you can't or don't want to send document with the right name, using subdomains is the best next option. This option, is not as common as adding the language after the domain, and that means, that people may not be used to it, although, it has some advantages, for instance;
Each language behaves like a whole new URL/site (almost).
People feel like visiting a dedicated site, not a subsection where the second language is relegated and may fail at any moment (some content may not be translated).
Some people are not familiar with their two letter representation of language, but everybody knows how his language is called and spelled.
It generates cleaner URL's.
It is believed that having subdomains increases appearance on SERPs (I don't have knowledge of this and it may have changed).
It's easier to have different layouts if you want to.
It's easier to set different servers according to language.
Of course subdomains have some disadvantages, like:
A bit more work to set properly from the server perspective.
Less collaboration from the part towards high ranking.
Some people may not expect it but expect a subfolder.
Next would be the subfolder option, as you show on the question. This is the recommended way if your main perspective is SEO since all the relevance of the domain stays on that same domain and each language helps to a common "pot" of ranking.
My perspective when choosing a solution, is never SEO, under any circumstance. Whatever ranking I get is due to the content itself and the best use I can give to technology. But I understand that my point ov view is not the most common.
One thing to consider also, is that you should provide some kind of explanation or help the user so he can take actions to change to the preferred language. It may be using icons, a tooltip, or any other method that works for your design and verbosity.
One thing to avoid, and you didn't ask for it, but is related; is using language autodetection. Lots of times, the user is in a different country or using a version of a browser that has a different language from what he can understand and the autodetction just makes a big mess. Offer the default version and a clear way to change it.
Most generic CoffeeScript/Backbone.js examples use attribute names like someFlag, however Rails prefers/requires some_flag.
Is anyone aware of discussion on the topic or a style guide that takes this into consideration?
I follow the convention of the server technology for my Backbone models.
For example, in my Rails applications, I set attributes using underscore names like some_value, and in my .NET applications I set attributes using capitalized names like SomeValue.
This makes it easier to integrate everything on the back-end. It's a minor inconvenience to remember to do this in the client side code, but once I'm deep in to a project, it becomes habit for that project.
The ease of the back-end integration is well worth the minor effort to use the convention that the server wants, in my opinion.
"There are only two hard things in Computer Science: cache invalidation and naming things."
-- Phil Karlton
http://martinfowler.com/bliki/TwoHardThings.html
I am looking at implementing URLMapping for a personal project. I am already aware that solutions exist so please do not answer suggesting I should use one.
What I want is to harvest the opinions of fellow developers and web users on URL mapping implementations. Specially I would like you to answer:
Which is your favourite implementation?
What do you like about your favourite implementation?
What do you not like about your favourite implementation?
How would you improve it?
I would like you to answer from two points of view:
As a developer
As a user
I would be grateful for any opinions on this matter, thanks!
I've only worked with django's URLConf mechanism. I think the way it relies on the urlpatterns variable is a bit flimsy, but I like its expressiveness in specifying patterns and dispatching to other url configurations. I think probably the best thing is to figure out your URL scheme first, and then try out a couple of solutions to see what matches best. If you're going hard-core REST using the full complement of GET/POST/PUT/DELETE, and checking the user agent's Accept headers, and all that, django will, by default, have you splitting your logic between URL config files and view files, so it might not be the cleanest solution.
However, since it's all Python, you might be able to do some more complex processing before you assign to urlpatterns.
Really, you want a system that does what you need. Your URL scheme is your API, so don't compromise on it based on the tools you use. Figure out your API, then find the tools that will let you do that and get out of your way.
Edit: Also do a google search for "URL scheme design." I found this without much effort: http://www.gaffneyware.com/urldesign.htm. Not comprehensive, but some good advice gotten from looking at what flickr does.
Well, I should have noticed the url-routing tag shouldn't I? :-) Sorry about that.
jcd's experience mimics mine - Django is what I use too.
I like the fact that the routes for an app reside within the app (in urls.py) and can just be included into any projects that might make use of that app. I am comfortable with regular expressions, so having the routes be specified in regex doesn't phase me (but I've seen other programmers scratch their heads at some more uncommon expressions).
Being able to reverse a route via some identifier (in Django's case by route's name) is a must. Hardcoding urls in templates or controllers (view in Django) is a big no-no. Django has a template tag that uses the reverse() method
The one thing I wish I could do is have the concept of default routes in django (like Rails does or even Pylons). In Django every route has to map to a view method, there is no concept of trying to call a certain view based on the URL itself. The benefit is that there are no surprises - your urls.py is the Table of Contents for your project or app. The disadvantage is that urls.py tend to be longer.
While I have experience developing Rails apps in English, I am a blank slate when it comes to handling globalization, so please don't shoot me in the head if my question 'doesn't make sense' :)
I have been asked to add multi language feature to a part of a Rails app that I am working on. Initially its only going to be 2 languages, French and German. The content that will be translated (which is in English now) is rendered using partials at the moment hence I am getting a bit inclined on creating partials with different languages and then based on the users language selection call the relevant partial - Would you recommend this approach?
Although it seems a heavy weight solution for this particular purpose, but I am also looking at the Rails Globalize plugin. This seems to appeal if I look at the long term gains, something like what if later I am asked to translate the entire app.
Any insights on what would be a proper structured approach to handle globalization in Rails?
Many Thanks
Have you had a look at the i18n (internationalization) API that is in Rails itself as of 2.2? It makes it easy to store your language translation files as .yml files, so a fr.yml and a de.yml or whatever. It also steps through different approaches of making languages accessible via browser prefs, or URLs, subdomains, etc. In your HTML template files you use symbols to specify the keys for the string you've translated. At least in my basic usage and testing, it was very easy to work with.
I preffer using translator instead of Rail's i18n, since the former handles "scoping of translation" automatically. I recommend you give it a look.
This is a great article on how to use Ruby's GetText to localise you Rails App.