Building APIs with Swagger

Designing and coding APIs in Node.js.


Getting an API design right demands far more than just figuring out which calls should do what. Public APIs — APIs meant to be used by people other than their creators — present a special set of challenges that can inform all API design. Even private APIs often find themselves with unexpected users, and can last far longer than was planned. Apigee faced the special challenge of creating a marquee API, an API for managing its APIs.

What comes first? The API or the code? Who is the API really for, and how important is the long-term maintenance of the API? Where does documentation fit? Answer these questions, and you can find the right approach.

Read more…

Comment: 1

Learning the Web

Finding a gentle entry to a big space


The Web welcomes, but it’s awfully big. While HTML, CSS, and JavaScript may all be appropriate entry points for newcomers who want to create, finding a solid starting point can be complicated. Social media has minimized the level of HTML and Web knowledge people need to start contributing, but when it’s time to make the jump, the Web offers perhaps too many options.

Part of the challenge is that HTML, CSS, and JavaScript may be the marquee technologies, but they’re not actually what hosts a website or app. Setting up a site requires an additional set of technologies, from domain names to hosting to web server choices. Setting up a site – long before you get to packaging an app! – requires mastering an additional technical toolset and vocabulary that will help you navigate where you need to put your projects. Our free report, Getting Started with the Web, provides the core foundations beginners need.

Those aren’t the only barriers, though. Read more…

Comment: 1

Renaming isomorphic JavaScript?

What you need to know to make an informed choice.

Abbott and Costello performing "Who's on First?"

Abbott and Costello performing “Who’s on First?”

Abbott and Costello’s signature wordplay sketch “Who’s on First?” is one of the most renowned comedic routines of all time. Trying to describe the routine here will do it little justice, you’ll just have to watch it yourself. As funny as it may be, the sketch reveals a crucial fact: names are important. Good names should be self-explanatory, precise and reveal intent. Bad names leave people confused and aggravated and should be avoided at all cost. When we write code, we must always think about variable names, function names, file names, etc. But naming things is hard. Phil Karlton probably said it best: “There are only two hard things in Computer Science: cache invalidation and naming things.”

Since Node.js was first released in 2009, many developers have started discussing and implementing ways to share JavaScript code between the web application server and the browser. This sharing of JavaScript code allows for assembling web pages on either the client or server, with the benefits of faster initial page load times and improved search engine optimization. The name of this approach was coined by Charlie Robbins and later popularized by Spike Brehm as “isomorphic” JavaScript. Such applications are isomorphic in the sense that they take on equal (ἴσος: isos) form or shape (μορφή: morphe) regardless of which environment they are running on, be it the browser or the server.

Read more…

Comment: 1

CSS fundamentally transforms

Enabling the creation of maintainable sites and apps that look great across a variety of different devices and contexts.


Choose your Learning Path. Our new Learning Paths will help you get where you want to go, whether it’s learning a programming language, developing new skills, or getting started with something entirely new.

CSS is different. Cascading Style Sheets provide a text-based way to describe what web pages should look like, but it isn’t a programming language and it relies on HTML document structures as a foundation. You need to have a grasp of HTML before you start CSS, but CSS doesn’t look anything like HTML. Nor does it look like JavaScript, the most common programming language on the Web. Whatever your background, getting comfortable with CSS’ unique approach can take some work.

CSS’ declarative model can be uniquely efficient, but requires an understanding not only of the features you want to use but the approach you want to take in decorating a document tree. That means understanding the document tree (and there may be many variations as you apply the same style sheet to multiple documents), the selectors used to identify points on the tree, the cascade that resolves conflicts among selectors, and the properties applied to that tree. Of course, the properties interact with each other and a shared model, so you’ll need to understand how the properties how to make those interactions produce your vision.
Read more…

Comment: 1

Proposing CSS input modality

:focus'ing on users.

Image of a camera lens artfully out of focus

Editor’s note: The author would like to acknowledge her co-author, Brian Kardell, who contributed many insights to the ideas presented here, along with a substantial number of the words.

Web developers and web standards authors alike strive to live up to the promise of “universality” — the idea that the web should be available to all. This concept drives many innovations in web technology, as well as being fundamentally built in to the philosophy of the open standards on which the web is based.

In order to achieve this, we frequently find that having some carefully chosen information about how the user intends to view the content (a concept we’ll refer to in this article as “user context”) allows web developers to create more flexible and useful user experiences. In this post, we’ll lay out a case that it’s time to expand our view of user context to include the concept of modality (how the user is interacting with the page), but before we flesh that out, let’s take a look at “user context”.

Read more…

Comment: 1

The Web welcomes

Access not just to content, but technology.


“They learn a bit of Web stuff, and the next thing you know they think they understand programming.” I’ve heard variations of that lament for the past two decades. I’ve heard it less lately, because so many recent computing professionals built their technical careers from that bit of Web stuff.

The Web succeeded in large part because it was the easiest way for people to create electronic content and share it. Indexes and search engines made it easier to find that content. While administering files on a server and learning HTML weren’t trivial, they were much more approachable tasks than creating and distributing traditional (now largely considered desktop or native) applications.

For the most part, they still are easier.
Read more…

Comment: 1