OpenAPI Specification

OpenAPI Specification v2.0 – formerly known as Swagger RESTful API Documentation Specification.

Swagger™ is a project used to describe and document RESTful APIs.

The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages. Additional utilities can also take advantage of the resulting files, such as testing tools.

Explain Shell

Here’s a good resource for all of those who is trying to learn shell and/or figure out complex commands with lots of parameters and pipes – Explain Shell.

ExplainShell

You just paste the command and hit the “Explain” button, and the site will decompose the command into parts, providing relevant parts from the manual pages.  There are a few examples to try it out on too.

JavaScript debugging tips

I came across this blog post which provides some very handy tips for debugging JavaScript in the browser.  My favorite top three are:

Display an object in a table format for an easier view

var animals = [
   { animal: ‘Horse’, name: ‘Henry’, age: 43 },
   { animal: ‘Dog’, name: ‘Fred’, age: 13 },
   { animal: ‘Cat’, name: ‘Frodo’, age: 18 }
];
 
console.table(animals);

with this output:

console.table

Unminify code as an easy way to debug JavaScript

unminify

Custom console log messages

console.todo = function(msg) {
	console.log(‘ % c % s % s % s‘, ‘color: yellow; background - color: black;’, ‘–‘, msg, ‘–‘);
}
 
console.important = function(msg) {
	console.log(‘ % c % s % s % s’, ‘color: brown; font - weight: bold; text - decoration: underline;’, ‘–‘, msg, ‘–‘);
}
 
console.todo(“This is something that’ s need to be fixed”);
console.important(‘This is an important message’);

for this result:

console.log

Very handy stuff!

Bitbucket Pipelines Beta announced

BitBucket blog announces Pipelines Beta (coincidentally after I’ve spent about a week playing with Jenkins).  These guys are dropping their Bamboo Cloud CI solution and instead provide this:

It looks a lot like TravisCI, but on steroids!  Very good news!

GitHub private repository contributions on your profile

GitHub blog says that from now on your profile can include the private repository contributions on your profile.

github private repo contributions

When enabled, these can make quite a difference in the number of the green boxes, showing your GitHub activity.  Here’s an example from mine.  Before enabling those, showing only Open Source contributions:

GitHub mamchenkov before

And here’s one after, including private repository contributions:

GitHub mamchenkov after

Indeed, it is a more accurate representation of my GitHub activity.  Given that these days most of my private repository activity happens on BitBucket and not on GitHub, this is quite surprising.

Google vs. Oracle : API vs. implementation

Slashdot is running the story about the Google vs. Oracle court case.  I thought this bit was rather brilliant:

Schwartz’s second attempt at the breakfast menu analogy went much better, as he explained that although two different restaurants could have hamburgers on the menu, the actual hamburgers themselves were different — the terms on the menu were an API, and the hamburgers were implementations.”

Programming and Greek

One thought that cracks me up every now and then is about Greek programmers.  In Greek language, instead of a question mark a semicolon is used.

Greek

In many programming languages, a semicolon is used to represent the end of statement.  So, this:

$a = $b + $c;
print $a;

to Greek programmers must be looking like this:

$a = $b + $c?
print $a?

I don’t know about you, but to me this would be a constant confidence issue.  It’s almost like I’m not sure what I’m going and asking the computer to confirm.

I’m sure though they have their ways of working around this …

By the way, while reading through the Wikipedia article linked above, I thought that the possible origins of the question mark were quite interesting:

questio

 

That would also explain why not all the languages are using the question mark character.

GitHub unlimited private repositories – a better world or a perfect disaster?

github unlimited repositories

Today I was super excited to read the following in the GitHub blog:

We couldn’t be more excited to announce that all of our paid plans on GitHub.com now include unlimited private repositories. GitHub will always be free for public and open source projects, but starting today there are just two ways to pay for GitHub.com:

  • Personal: $7/month
  • Organization: $9/user/month, $25/month for your first five users

One of the very best things about Git and other distributed version control systems is the ability to create a new repository without asking permission or getting approval. While this has always been true for our public plans, it hasn’t been the case for individuals and teams working together in private. All that changes today.

After all, it was the pricing around private repository that pushed me towards BitBucket.

Working for a small startup with a small development team and lots of client projects that require private repositories, GitHub was too expensive of an option.  So we’ve moved all private repositories to BitBucket, which charges for the team size.  We still use GitHub for all of our Open Source work, and for the client projects where we need to work with external teams (usually, developers on the side of the client).

Can we move all our stuff back to GitHub and just use a single service for all our code, pull requests, code review, etc?  That would make a world a better place.  Let’s see …

github

Wait, what?  Our GitHub organization has 5 members and 18 external collaborators.  And, well, another 5 pending invitations to the external collaborators.  But all of these are summed up into the 28 users (!!!).  Currently, we are on the Bronze $25/month plan, which comes up to $300/year.  The new plan with unlimited repositories, as indicated on the screenshot above, will be $2,784/year.  That’s almost a 10 times increase!

Thanks, but no thanks.  Right?  Well, not really.  The GitHub blog post also says the following:

We want everyone to have a plan with unlimited private repositories, but don’t worry—you are welcome to stay on your current plan while you evaluate the new cost structure and understand how to best manage your organization members and their private repository access. And while we’re currently not enforcing a timeline to move, rest assured that you’ll have at least 12 months notice before any mandated change to your plan.

This is not very friendly.  This means that while upgrade to the new plan is now optional, it might not be so in the future.  Sure, you’ll get a warning ahead.

Dear GitHub!

I understand that you are a profit-oriented business and you need to make money.  But I think you’ve made a mistake somewhere here.  I hope you’ll re-evaluate this thing.  Otherwise, I’ll have to move away – either to BitBucket or GitLab.  And it’ll be a sad day.  I know, I’m not your largest client, but I’m sure there are many like me.

Yours truly, Leonid.

Furthermore, thinking about this, I suspect that external collaborators are being charged twice.  Sure, they can have their own repositories as well, but collaboration often involves forks and merges between multiple repositories of the same project.  So, to support this collaboration, I need to pay for the external collaborator to have access to my private repositories, while he also needs to pay on his side to be able to fork the private repository into his organization.

I think organization shouldn’t be charged for external collaborators.  Extra features for organization members – like team-mentions, finer access control, etc – can provide the incentive for the companies to pay.  But the way this looks now is just too much.

Algorithm Economy and Containers

Containers (Docker, et al) have been getting all the hype recently.  I’ve played around with these a bit, but I’m not yet convinced this is the next greatest thing for projects that I am involved with currently.  However, it helps to look at these from different perspectives.  Here’s a blog post that ties containers to a new term that I haven’t heard before – algorithm economy.

The “algorithm economy” is a term established by Gartner to describe the next wave of innovation, where developers can produce, distribute, and commercialize their code. The algorithm economy is not about buying and selling complete apps, but rather functional, easy to integrate algorithms that enable developers to build smarter apps, quicker and cheaper than before.

Best Practices for Designing a Pragmatic RESTful API

An API is a user interface for developers. Put the effort in to ensure it’s not just functional but pleasant to use.

Vinay Sahni has a rather lengthy, detailed, and well-rounded post on how to design a good RESTful API.  It covers pretty much everything from URL structures and parameters, request methods, to error handling, documentation, and coding style.