My Guidelines for designing a restful APIs so frontend devs won't ask where I live

As a backend developer, I have to play nice with the frontend people. Let's face it, I don't want to be prison shanked on the lunch line. Easier said than done because of the different ideas that people have floated around like these three.

• JSON:API
• OpenAPI
• GraphQL

Each one of these have pros and cons but those are academic papers that I don't care to write right now. But I've worked and talked to a lot of frontend devs and they don't really care if we use any of the three examples that I gave. 

For them, a good API:

1. Is well documented - makes sense; I'm a fan of drfdocs. Also Swagger gets a lot of mentions.
2. Is versioned - good point; because changes to existing ones break too many things
3. Is idempotent - to be honest I had to look this one up but it's the same idea of pure functions. Given the same input, it should return the same value (output)
4. Uses HTTP errors correctly - For example, don't return errors with 200 status. Oops.
5. Uses HTTP verbs sensibly - they want none of that 'GET /v1.0/delete/100' because that shit is stupid.
6. Is NOT SOAP - dear lord up above in heaven, not ever SOAP. Ever

I also don't like SOAP. 

Dealing with global web assets on Django

Dealing with global web assets on Django, my thoughts.

Working with Django, often your default mode of thought is apps. App are like these small self-contain programs that have their own urls, views, templates and the web assets that come with templates. Web assets, I mean those css (or Sass or Less files), images and maybe some JavaScript.

But when you start thinking long term, as far as templates go, apps will prove unmanageable. You'll start thinking of breaking then into smaller reusable units while leveraging template inheritance. Which leads us to the dilemma, how do we handle the global web assets?

My first idea was just put it on the /static folder. It works but not a good idea because a standard django .gitignore will exclude the /static folder.  Another thing, /static folder is where the django-admin collectstatic command puts all files it gets from the your dependency modules. It's not uncommon to have hundreds of MB inside this folder - hence, you don't commit them into repos.

So, I had to figure out a way that allowed to me get around the .gitignore rule (which I won't edit - they are standard for a reason) with the assets. What I ended up with is

1. Putting the global, shared web assets in an /assets folder
2. Inside the /assets folder are subfolders for css, js, img, font
3. Change my django configuration to handle it.

STATIC_ROOT = str(ROOT_DIR('static'))

STATICFILES_DIRS = [
    ('projectA1', str(ROOT_DIR('assets'))),
]

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
]

The ROOT_DIR function is just a helper function that prints out the path to static relative to the root directory.

So anyway, an example usage then is like .. href="{% static "projectA1/css/style.css" %}" which is pretty nice. Details are here.

Quick Letter Avatars for List in NativeScript

Letter Avatars are these elements often associated with Gmail - especially on it's Android client. So, being a programmer lacking in design skills, I decided to copy them for a Nativescript app I'm working on that had lists.

My approach to this was just to use a Label element and CSS. It's hacky but it works and in my world if it works it's not stupid.

So, we start on the component template:

 <GridLayout rows="*">  
  <ListView [items]="ordersList" (itemTap)="onOrderTap($event)" class="list-group">  
   <ng-template let-order="item" let-odd="odd" let-even="even">  
     <GridLayout [class.odd]="odd" [class.even]="even" columns="auto, *, auto">  
       <Label class="lavatar" text="VP" style="background-color: goldenrod; color: white;"></Label>  
       <StackLayout col="1" class="item-text">  
         <Label [text]="'#' + order.number"></Label>  
         <Label [text]="'Order by ' + order.guest_email"></Label>  
         <Label [text]="order.date_placed | date:'MMMM dd yyyy'"></Label>  
       </StackLayout>  
     </GridLayout>  
   </ng-template>  
  </ListView>  
 </GridLayout>   

The important thing here is the Label with the class "lavatar" which as the following rules:

.lavatar{
    text-align: center;
    font-size: 20;
    font-weight: bold;
    padding: 18;
    border-radius: 40;
    border-color: salmon;
    border-width: 0.5;
    width: 64px;
    height: 64px;
}

The border-radius is what's actually rounds the element.

Unfortunately this rule only works on "known" dimensions - width and height. For a more dynamic solution, I think you'll have to keep looking.

Settings the colors is based on the fact that CSS rules have the "cascade rule" so the final style rule applied is what's on the element. That's why the Label has a style attribute despite knowing it's in bad taste.

 Oh well.

Typescript is what JavaScript should have been

When Brendan Eich added JavaScript to the Netscape browser some 20 years ago, he had roughly a month to do it and, context-wise, JavaScript was added to the Netscape browser as a reaction to the popularity of Java - applets - at that time.

JavaScript was something you could use to interact with the browser via small programs and scripts - think sub 1k lines of code. Unfortunately, that's no longer the situation. It has become common to see 1 million lines JavaScript projects. Projects of this size are unmanageable:

1. Tooling is bad - barely there intellisense, unsafe or no refactoring

2. Development flow sucks - you can't check for common errors until you refresh the page

3. JS Code bases of these sizes are hard to reason about for many reasons like duck typing especially if you got code with bad or lazy naming conventions

This is where Typescript comes in.

1. TypeScript's static typing and annotations are great for catching errors on the tool rather than waiting for a page refresh

2. Code is easier to reason about; example, function params are known if you're using interfaces

3. TypeScript allows safe refactoring and good intellisense support

4. Although from Microsoft, TypeScript is open source with a clear roadmap with rapid releases - typically 3-4 months

But Typescript is not without faults.

1. TypeScript is superset of JavaScript. So any valid JavaScript is also valid TypeScript. In that case, if you write crappy JavaScript, you still get crappy TypeScript. Somewhat fixed if you read and apply Douglas Crockford's advice in his seminal book, JavaScript: The Good Parts

2. Typings. Sort of an edge case problem because some javascript libraries don't have typings thus we don't have intellisense for that library

The good stuff out-weights the bad parts for me. Typescript is what JavaScript should have been.

Making sense of WPF layouts

I started out as a Swing developer and I have the Java Foundation Classes book to prove it. But Swing never really caught on and so I started working with C# and WPF. Windows Presentation Foundation (WPF) isn't what you'd expect for making desktop applications. It kinda feels like making web applications since you "describe" the UI via a XML-like language called XAML. This isn't really a bad thing just different.

I could go on about WPF being different but at the end of the day the foundation of a desktop app is the layout it's built upon. This is what I've learned.

1. By default, WPF apps have a base "Grid Panel" layout. Get rid of it and use "Dock Panel" as your base.
   Dock Panels are the same to Border layout in Swing. The idea is to place the menu on top (DockPanel.Dock="Top"), status bar bottom (DockPanel.Dock="Bottom") and put a "Grid Panel" at the center. Now you have a well-behaved desktop app that reacts well to window re-sizes. 
2. The Grid Panel is like Swing's GridBagLayout only easier to use.
3. Use the Alignment properties in combination with Margin to position elements in a panel; avoid fixed positions (using the x,y coordinates) unless you have a really, really good reason to do so. They don't work out so well when tested against various screen resolutions.
4. Also, the same for height and width. Use min and max properties instead.
5. Don't use blank "label" components to separate components. Use the margin and padding properties. For example, if 2 buttons are side by side, don't put a blank label in-between them to create space.

In Android: Long press = right click

Share anyone?

I just sat through an IPad demo for education. The demo was basically about using IPad as a teaching tool for college/university level instruction. It was pretty good but then I notice something wrong amiss with the IPads. You can't just share data between apps like I just can't just pass links from say Safari to Chrome.You have to do a copy-paste procedure which is kinda stupid and unnecessary.

For Android old-timers, doing stuff like that is a piece of cake. Just do a long press and you will be presented a "Share via" option and then you can send where you want it and the target know what to do with it.

New Android people seem to be limited to point-click and swiping with their phones and/or tablets. If they do a long presses on stuff in their phones they'll discover a whole new layer of features to play around with.

Android programmers know this as "Intents". In Android, the 3 core components of an application — activities, services, and broadcast receivers — are activated through messages, called intents. Thus allowing my app to pass data and stuff to other apps. That's cool in every which way you look at it. Which begs the questions:

Why the copy-paste procedure Apple?

Edit: Apparently, Windows Phone does the same with Bing Search and Internet Explorer. That's sad.

Getting that layout just right

Getting that layout just right or more like changing the layout into something else I like. That's right, changing the look of our web application. Now, since this is tutorial - we are not going to reinvent the wheel. So, no wires, drafts, sketches or whatever remotely artistic. We go the cowards way and look for a cop out. So drop that pad and pen (or pencil) and open you're browser and point it to freecsstemplates.org or oswd.org. We are going to pick one out and use it. so browse, pick and download a design.


For me I am using a fixed-width design with two-columns from freecsstemplates.org. Its called Republic.

Now, you should be able to read html and some css for this part. When you have figured out how the republic template works, you know its time to use it and replace ours.

So, we open up Tapestry's Layout component. Almost everything in Tapestry is a component. The Layout component comes in two parts - the Layout.tml (just like you see in the pic) and the Layout.java (which is the java class). Layout.java (if haven't figured it out) is in the source packages.

Now we are going to do a simple find and replace for this part, but not everything. For example:

 <div class="post">  
   <div class="title">  
      <h2>${title}</h2>  
   </div>  
    <div class="entry">  
      <t:body/>  
    </div>  
 </div>  

If you see tags like a ${title} and the <t:body/>, you should be aware that these are page variables that Tapestry will replace. So you will have to work around them to get the look you want. It should be fairly clear that anything with a "$" or "t:" prefix is connected to something in our Tapestry application.

That should be easy.

After recoding the html, now you need to replace the css. Now within the Web pages there should be a Layout.css file in a (duh) layout folder. Open that and then open (use notepad) layout.css of the republic template. Copy and paste over. Don't forget about the image folder. And BAM! you got a new look.

BTW, you might need to clean the cache of your web browser and/or application server (assuming that you're using something else other than jetty *big grin*)

This is how it should look now after a few minutes of playing around with the HTML and CSS. Don't worry if you don't like it - you could always change how the thing looks quite easily.

Remember, if you want to get your grubby hands on the code you need to learn how to use SVN. Again, this tutorial project is hosted by kenai.com at this URL: http://kenai.com/projects/addressbook-tap.

Hoots!