Skip to content

Instantly share code, notes, and snippets.

@sranso

sranso/fluent.md

Created April 23, 2015 17:06
Show Gist options
  • Save sranso/1453d64208e13cb89806 to your computer and use it in GitHub Desktop.
Save sranso/1453d64208e13cb89806 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
fluent.md

Designing a Beautiful REST+JSON API

Les Hazlewood (Stormpath)

  • fundameantally two types of resources
    • collection resource
      • e.g. /applications
    • instance resource
      • e.g. /applications/a1b2c3
  • behavior
    • get = read
    • put = can be used for create/update scenarios
      • client knows ahead of time what the id of the resource is
      • can also be used for full replacement, but has to have all the data in that req
    • post = can be used for create/update scenarios
      • can create a new one on the collection
        • e.g. POST /applications -> creates a1b2c3
      • can update on the instance
        • e.g. POST /applications/a1b2c3
    • delete = delete
    • head = headers, no body (metadata)
  • media type
    • defines behavior
    • media type != schema
    • most only need 2/3 custom media types
      • collection resource
      • instance resource
  • base url
    • KISS
  • versioning
    • url (preferred)
    • media-type
      • application/foo+json;application&v=2
    • increment only when there is a backwards incompatible change
  • use camelCase (bc javascript)
  • date/time/timestamp
    • use the standard: ISO 8601
      • ex { ... "createdAt": "2013-07-10T18:02:24.343Z", "updatedAt": "2013-08-10T18:04:26.349Z", ... }
    • use UTC
    • include both createdAt and updatedAt
  • to send data back in res?
    • get -- obv, yes
    • post -- return when feasible
  • href

  • instance reference

    { "meta": { "href": "https://api.stormpath.com/v1/accounts/x7y8z9", "mediaType": "application/ion+json", }, "directory": { // for instance; "groups" for collection "meta": { "href": "https://api.stormpath.com/v1/accounts/x7y8z9", "mediaType": "application/ion+json", } } }
  • reference expansion (entity expansion, link expansion)
    • GET /accounts/x7y8z9?expand=directory
    • GET /accounts/x7y8z9?fileds=givenName,surname,directory(name)
  • collections
    • a first class resource 'citizen'
      • own href/metadata
      • own properties
      • diff from all other collections
    • should have
      • offset
      • limit
      • size
  • sorting
    • GET ../accounts?orderBy=surname,givenName%20desc
  • search
    • starts with ?email=joe*
    • ends with ?email=#company.com
    • contains ?email=foo
    • range queries
      • [] include, () exclude
      • ../accounts?creaedAt=[2014-09-01,2014-09-15]
  • many to many
  • batch crud
    • delete all company.com accounts
      • DELETE /accounts?email=*@company.com
    • caching is bypassed entirely :( so it isn't updated
  • errors
    • be as descriptive as possible
    • developers are your customers
  • other notes/advices
    • avoid sessions when possible
    • authorize based on resource content, not url
    • use existing protocol: oauth 1.0a, ouath2, basic over ssl only
    • custom authentication schee:
      • only if you provide client code/sdk
      • only if you really really know what you're doing
    • use api keys instead of un/pwd
  • 401 vs 403
    • 401 "unauthorized" really means unauthenticated "you need valid credentials for me to respond to this req"
    • 403 "forbidden" really means unauthorized "i know what you're asking for but you're not allowed to access it"
    • 404 means "that doesn't exist"
  • ids
    • should be opaque
    • should be globally unique
    • avoid sequential numbers (contention, fusking)
    • good candidates: UUIDS, 'Url62' (base62 encodings of bite-arrays(?))
  • http method overrides
    • ok to support for clients (eg legacy clients) that don't support things like delete/patch POST /accounts/x7y8z9?_method=DELETE
  • other
    • use CORS instead of JSONP

gitting more out of git

Jordan Kasper (StrongLoop)

  • can push/pull from any repo accessed via a web protocol
  • git branch -vv
    • show what a branch is tracking
  • git branch --no-merged
    • only branches that haven't been merged into the br that you're on
  • git diff master stuff
    • ???
  • git diff master..stuff
    • what's been done in that br
    • master + stuff just pointers to end commit of those branches, equivalent to git diff b9bdb02 b86e65d
  • every single commit is a snapshot of the entire repo at that time
  • git commit --amend -m "New commit message."
    • rewriting history with amends -- git will think it's a change but it's not. can be tricky.
  • git reflog
    • will show amends, whereas git log does not
    • holds all the activity
    • never gets pushed to a remote
  • git add forgotten.js git commit --amend
  • modifying older commits
    • affecting all of the ones after it (everything built ontop of the last thing)
  • interactive rebasing
    • git rebase --interactive HEAD^^^
      • head of current branch, go back three commits
    • git commit --amend
    • git rebase --continue
  • three states of a repo
    • head (files committed to your repo)
    • staging area (files added)
    • working area (files edited)
  • git reset --soft HEAD^
    • repo marker has gone back one place -- from staging to working
  • git reset --mixed HEAD^
    • resets the index but not the working tree (i.e., the changed files are preserved but not marked for commit) and reports what has not been updated
    • this is the default action
    • files are not in staging, not in repo
  • git reset --hard HEAD^
    • resets all three states
    • git reset --hard HEAD@{1} -- can find HEAD you want in reflog if you accidentally reset HARD and deleted a commit
  • head notation
    • HEAD^ back one place from current head
    • HEAD^^ back two place from current head
    • HEAD~n back n places from current head
    • HEAD@{i} back to reflog index i
  • git stash
    • git stash --include-untracked
    • git stash apply -- pulls off the top of the stash
    • git stash drop stash@{0}
  • logs
    • git log --oneline
    • git log --oneline graph
    • filtering
      • git log --no-merges
      • git log --author="jakerella"
      • git log --before="2014-07-01"
      • git log -- src/js/
  • blame
    • git blame src/js/utilities.js
    • git L3,5 blame src/js/utilities.js
  • git bisect start
    • used to find what is breaking
    • used when there's a broken branch
    • git bisect bad -- telling bisect i'm on a bad commit
    • git bisect good b9bdb02 -- this is the last good commit
    • git bisect good -- git informs you what the first bad commit was, and is like "cool we're done"
    • git bisect reset -- get out of the detached state
  • merge
    • non-divergent changes
      • git merge feature --no-ff -- if don't want to ff this time so you can see the merge history/commit
    • divergent changes
      • git merge commits have two parents. if it has one parent then it's a simple commit
    • conflicts 
      <<<<<<<< HEAD
text only in master
==========
same line, diff text in branch
>>>>>>>> feature
  • rebasing
    • be careful if you have already pushed to a shared branch b/c it rewrites history
    • git rebase --abort
    • when you rebase, always do it by default and have everyone rebasing -- too dangerous otherwise
      • git pull --rebase
      git config branch.master.rebase true
git config branch.some-other-br.rebase true

git config branch.autosetuprebase always
  • cherry pick
    • taking a commit from a dead branch and moving it to the new feature
    git co new-feature
git cherry-pick d42c386
git co new-feature # takes cherry-picked with you
git br -D old-feature
    • if you do this ^ then you should not merge old-feature into master b/c it will be a conflict!

transform into your team's web security guru

github.com/steilhet/FleuntTalkSecurityInfo

  • don't rely on tools

Dirty Performance Secrets of HTML5

Andreas Gal (Mozilla)

  • use JIT to profile your app/speed
  • repositioning boxes in HTML5 takes a long time -- position: absolute; makes things faster
  • use video, not animated gifs
    • takes lots of memory; vids are much more efficient
  • stroking is slow
    • drawing a line
  • think in device pixels
  • browsers use GPUs more than CPUs now... canvas can help speed things up
  • understand layer optimizations
    • how does browser split up the img rendered into layers?
    • give GPU more manageable smaller pieces to render/manipulate/animate
  • use workers

ECMAScript Harmony: Rise of the Compilers

Brendan Eich

  • compiles ES6+ code to ES5 friendly clode
    • babeljs
    • clojurescript
  • unity
  • check out webgl already!

Making Badass Developers

Kathy Sierra (SeriousPony)

so good!!!!!

Functional Programming and Curry Cooking in JavaScript

Stefanie Schirmer (Etsy)

  • abstraction
    • make an operation obvious what it's supposed to do
    • func abstracts from a sequence of statements function roastSpices() { console.log('roast!)' }
    • a higher order func abstracts from a func spices.sort(sort\_by('name'));
    • gives us hierarchy to structure our program
  • closures 
    function localGreeting() {
  var captured = 'namaste';
  return function() {
    console.log(captured);
  };
}
  • curry
    • 1 func w/ n args --curry--> n funcs with 1 arg
    var fCurry = function(a) {
  return function(b) {
    return function(c) {
      return console.log(a, b, c);
    }
  }
}
  • map
    • provides func to each event in array

conquering inexpressive web uis with d3.js

travis smith

  • the problem: templating can get complicated with lots of if-else's
  • d3
    • selectAll what you expect to find, append data, enter, and then append
    • remove is easiest way to remove from DOM
    • ability to rescale d3.scale.linear()
  • can build extensions to d3

how to build an api service in 30 minutes with expressjs

randall degges (stormpath)

  • github.com/rdegges/btc-sms
  • used stripe (cc info), twilio, bitcoin charts, stormpath (stores users)
    • stormpath: used as express middleware
    • bootswatch: extensions/layouts for bootstrap
  • express quick tip
    • app.locals.anything = 'anything'; --> anything is now available to your templates!

nodejs: the past and the future

timothy fontaine

  • node
    • event-driven, reactive --> not new
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment