Swagger Schema

First, our database platform (InterSystems Iris) provided a way to get a Swagger spec (link) which pulls information from a target dispatch class. For the sake of this post, this is the relevant schema I was after:

{
  "paths": {
    "/some/url": {
      "post": {
        "description": "Extracted from ClassMethod Comments.",
        "summary": "Extracted from route comments.",
      }
    } 
  },
  "swagger":"2.0"
}

Now to loop over the swagger spec and get a list of records describing each API, we loop over a dictionary of dictionaries:

# Pass in the entire swagger data object
def processSwaggerRecord(jsonData):
  swaggerSpecs = []
  for path, spec in jsonData['paths'].items():
    for pathType, apiData in spec.items():
      record = {}
      record['url'] = path
      record['type'] = pathType.upper()
      record['Total'] = 0
      swaggerSpecs.append(record)
  return swaggerSpecs

Postman Schema

Next, we had several postman collections defined to test various aspects of our APIs. To do a rough gap analysis, I needed to extract the routes and request types so I could match each request against the swagger spec and create a tally. Here is the relevant schema in the exported postman collections:

{
  "info": {
    "_postman_id": "...",
    "name": "My Postman Collection",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [{
    "name": "Testing - Non-existant user",
    "request": {
      "auth": {"type": "oauth2"},
      "method": "GET",
      "url": {
        "raw": "{{url}}/some/url",
        "host": ["{{url}}"],
        "path": ["some","url"],
        "query": [{"key": "foo", "value": "bar"}]
      }
    },
    "response": []
  }],
}

Postman allows you to group requests in folders to an arbitrary depth. Both request and folder objects appear as records within the item property. Therefore, we can tell them apart based on the existence of either request/response properties (indicating a request) or an item property (indicating a sub-folder). Taking a request object, we want to extract the same information that we extracted from the Swagger data:

# pass in an item array
def processPostmanFolder(postmanFolder):
  output = []
  for request in postmanFolder:
    if 'item' in request:
      output += processPostmanFolder(request['item'])
    else:
      output.append(extractPostmanRecord(request))
  return output


def extractPostmanRecord(postmanRequest):
  record = {}
  record['name'] = postmanRequest['name']
  record['type'] = postmanRequest['request']['method']
  rawUrl = postmanRequest['request']['url']['raw']
  queryIndex = rawUrl.find('?')
  record['queryString'] = ''
  if (queryIndex > -1):
    record['queryString'] = rawUrl[queryIndex+1:]
    rawUrl = rawUrl[0:queryIndex]
  record['url'] = rawUrl[rawUrl.find('/'):]
  return record

Matching Requests

Since postman requests can have values defined where the swagger spec indicates variable data, we cannot rely on exact route matches alone. So, if we cannot find an exact match on the route, then we can try matching on just the static parts of the route:

def requestsMatch(swaggerAPI, postmanRequest):
  if ( (postmanRequest['type'] != None) and (swaggerAPI['type'] != postmanRequest['type']) ):
    return False
  if (swaggerAPI['url'] == postmanRequest['url']):
    return True
  #
  # If the routes contain parameters and/or environment
  # variables, try to match on just the static part.
  swaggerIndex = swaggerAPI['url'].find("/{")
  if (swaggerIndex > -1):
    swaggerUrl = swaggerAPI['url'][0:swaggerIndex]
    postmanIndex = postmanRequest['url'].find("/{{")
    if (postmanIndex > -1):
      postmanUrl = postmanRequest['url'][0:postmanIndex]
      if (swaggerUrl == postmanUrl):
        return True
      else:
        postmanUrl = postmanRequest['url'][0:len(swaggerUrl)]
        if (swaggerUrl == postmanUrl):
          return True
  return False

The Final Script

Now that we have all the basic pieces, it is time to put them together. For the postman collections, I decided to drop all the exported collection files in a ./data folder and define a tab-delimited file collections.csv where I can specify an intermediate CSV file and a collection specific tally column header for each source collection file. (I prefer having my script save each processed postman collection to a csv as a way to manually verify the script was working as intended.) Then it compiles a tally of how many times each request appears in a collection specific column. Finally, it generates the gap analysis report csv.

def process(swaggerFile):
  print("Loading Swagger File.")
  swaggerSpecs = extractSwaggerData(swaggerFile)

  # Get the defined collection catalogue list
  postmanCollections = loadPostmanCatalogue()
  fieldNames = ['url', 'type', 'applications', 'permissions check', 'permissions']
  tallyColumns = []
  postmanFields = ['url', 'queryString', 'type', 'name']

  # Loop over all exported collection files
  for collection, file, column in postmanCollections:
    print("\nLoading " + collection)
    postmanRequests = extractPostmanCollection(os.path.join('.//data//', collection))

    # so we can check our work if necessary
    saveToCSV(file, postmanFields, postmanRequests)

    # update tallies for each postman collection
    swaggerSpecs = tallyPostmanRequests(swaggerSpecs, postmanRequests, column)
    fieldNames.append(column)

  fieldNames = fieldNames + ['Total',
                 'summary', 'description']
  saveToCSV('.//API_Catalogue.csv',
            fieldNames, swaggerSpecs)
  return


#
# Update the request tallies in apiList based on the
#  requests in postmanCollection
#
def tallyPostmanRequests(apiList, postmanCollection, tallyColumn):
  for request in postmanCollection:
    match = False
    for record in apiList:
      if tallyColumn not in record:
        record[tallyColumn] = 0
      if requestsMatch(record, request):
        record[tallyColumn] = record[tallyColumn] + 1
        record['Total'] = record['Total'] + 1
        match = True
        continue
      if (match == False):
        print("Could not match postman request for " + request['url'])
  return apiList

If you have collections broken out topically, then the resulting tally columns can give you a rough picture of what your coverage looks like. For example, we had one collection that explicitly checked our secure APIs to make sure requests missing the necessary authentication returned 403 Reponses. Another collection could verify all the “missing input required” validation conditions. Another collection could be all APIs not requiring auth. etc…

The full code can be found here on my github account.

As it turns out, the server environment runs under the system user and doesn’t know about my ssh credentials. Enter the sshCommand config option!

First, open up your config file inside the .git directory. Then inside the [core] section, add an entry for sshCommand:

[core]
        repositoryformatversion = 0
        filemode = false
        bare = false
        logallrefupdates = true
        symlinks = false
        ignorecase = true
        sshCommand = ssh -i 'c:\\Path\\To\\.ssh\\id_rsa' -o IdentitiesOnly=yes -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no
[remote "origin"]
        ...

I was so happy the day my co-worker clued me into this. The trick to making this work on windows was putting the full path in single quotes and escaping the back slashes.

https://dev.to/ben/my-three-tips-for-maintaining-fitness-and-a-healthy-lifestyle-as-a-software-developer

http://shoptalkshow.com/episodes/257-hiring-rebecca-murphey-lon-ingram/

http://shoptalkshow.com/episodes/258-design-ethics-robyn-kanner-mike-monteiro/

http://itsalljournalism.com/251-tribeworthy-wants-to-be-yelp-for-news-consumers/

#132 – Share Often

SQL Injection Cheat Sheet.  There is a lot of good technical detail here, much more than I previously knew.  If you’ve never tried testing for vulnerabilities, this is a must read.

Big List of Naughty Strings – Dove tailing off that last one, this git repository is like it says.  Useful for testers and developers alike.

10up Best PHP Security Practices – Contains some WordPress specific examples.  This one is a good introduction for developers if you haven’t been programing with security in mind.

Basics of Web Application Security – a long read, but a good one.  The authors explain the principles of how to protect your application from malicious inputs and outputs.

Finally, I can’t post a list of security articles without recommending the Security Now podcast.  They cover a wide range of security topics from breaking down security vulnerabilities to security & crypto issues in the news.   This podcast is worth checking out.

Multisite 101 – This is a great primer e-book on the subject.  I highly recommend it.

Adapting a plugin to multisite (stackoverflow) – This is a good run down of some programmatic considerations you might need to make.

Remove “/category/” from your url base.  I would never have guessed the solution presented here.  However, I ran into pagination problems using this in combination with removing the default “/blog” slug on my root site.  In the end, this plugin fixed the issue which I found via this wordpress.org support thread.

Enable a theme for just one site (blog post) – Sometimes, it’s just helpful to see how its done.

Active plugins on multisite – I found this plugin helpful for getting an overview of all plugins within the network.  However, at the time of this writing, the plugin appears unmaintained.  I ended up forking it to fix a few issues that were reported through the support forums.  Here is the git repo of my fork for those interested.

Style Guide Pages

My initial starting point with WordPress was to manually create pages and posts to explicitly collect all the different types of content chunks from basic HTML elements on up. On test sites, I’ll add these to my primary navigation menu so they are easily accessible.  If you don’t have a test site, you can always publish them as private which will require you to login in order to view them.  If your theme makes use of page templates, make a page for each template and make sure you give them descriptive titles to match.

From there, you can add any other sample content that is representative of content as a whole.  Do you make extensive use of Gravity Forms?  Put together a sample form with all the different input types you use and include that.  Have you made custom short codes?  Add those as well with all the different attribute variations so you can see them in action.  Yes, this is a manual process, and I acknowledge that this is not my ideal solution.  However, even if you want to invest time in a tool of some kind, you will still need to assemble your examples.  You have to start somewhere.

Style Guide Shortcode

While following this pattern, I found myself copying some of the same markup around from post to page across the different sites I was working on.  Much of it was just so I could see how basic HTML elements were being styled and quickly confirm that base styles hadn’t changed.  That lead me to extract some of this sample content into a shortcode that lets you easily drop in stock HTML to any WYSIWYG editor.  I’ve extracted the shortcode into a plugin that can be found here: https://github.com/cambot/simple-html-styleguide.

Final Thoughts

I find the exercise of creating style guide pages and posts invaluable.  It helps at the start of a project when I’m setting up custom theme styles.  It also has benefits later on if you find yourself refactoring your style sheets or are iterating towards a new design.

Fortunately, testing is more about feedback rather than the specific tools you use.  If you don’t have the time or flexibility to invest in a style guide tool of some kind, starting with a manual process like this is a good starting point.  I’m looking forward to the day when I can take this to the next level.

Enter git filter-branch

• https://git-scm.com/docs/git-filter-branch
• https://git-scm.com/docs/git-gc
• https://git-scm.com/docs/git-count-objects

An Alternate Approach

If you have more sophisticated needs, there is a tool that builds upon git-filter-branch

https://rtyley.github.io/bfg-repo-cleaner/

Another use case

I wanted to move a small repository of helper scripts and template config files to my primary github account.  The problem was that all my username and emails were for the source git account.  I found this github help article outlining how you can change the user name and email of a committer and author within your history.

Podcasts

Shop Talk Show

A great show about a wide range of web topics.  Never a dull moment with the Dave-o-Tron soundboard of 1000 effects.  Their interviews are well executed and the rapid fire episodes really pack in the knowledge.  Recommended episodes:

• Chris and Dave discuss “The Cathedral and the Bazaar”
• Interview with a Hacker

Code Pen Radio

Gets into the nuts and bolts about how codepen.io has been built, covering both technical and business topics.  I started listening a few months back as they were covering their redesign with Sparkbox and liked it so much that I’m starting from the beginning.  Some of my favorite episodes:

• 007 – Complexity
• 014 – Security
• Redesign pt 1, pt 2, pt 3, pt 4
• 055 – Experts

It’s All Journalism

The interview of Dan Newman and Tejas Mistry about NPR one was my gateway into this podcast, and man was I hooked.  I find it to have an interesting range of thought provoking topics and discussions from the tech supporting modern journalism, to the people producing (and checking) the news.  Now that I’m in the world of Journalism and Media education, this podcast has been very helpful in broadening my awareness of these topics.  Interesting episodes:

• Street level reporting of the Baltimore Protests
• Global news has a local impact
• Free speech in the age of mass surveillance
• Periscope curious?

Support Ops

Customer support has been a part of every job I’ve had over the last 10 years.  It’s easy to forget how to deal with people when you’re pushing code all day, and I find this podcast is a nice way to keep a toe in the support waters.  Some interesting episodes:

• Case Study: Buffer’s experiment on eliminating the management hierarchy.
• Supporting decisions you don’t like… because it’s inevitable.
• Leaving gracefully

Responsive Web Design

Karen McGrane and Ethan Marcott interview the people who make responsive designs happen.  After a while, the episodes tend to sound very similar, but the ones that stand out really stand out.

Security Now

This is the most recent addition to my list.  At 2 hours a piece, these episodes can be a slog to listen through, but they cover all kinds of internet security topics ranging from deep dives into security bugs to interviews of people providing security products on the internet.

• Verifying iOS App Conduct
• Doing it Wrong
• Security is Difficult

From Python Import Podcast

This podcast went silent a while ago, but there are a few good episodes I highly recommend listening to:

• 02 – The Zen of Python Pt 1
• 03 – The Zen of Python Pt 2
• 16 – Katie Cunningham and the Podcast of Doom

The first is for defining a list of contact info for a website.  Think email, business hours, phone, fax, etc.  The second is for defining a personal staff profile.  Think name, contact info, website, etc.  The description list syntax is straight forward.  First, you have your <dl> element, aka the definition list.  This is analogous to an ordered or unordered list (<ol> or <ul> respectively).  Then it’s followed by a set of term and definition elements (<dt> and <dd> respectively).

I have a particular way I like to style description lists when used like this.  However, since I actually need to implement this pattern somewhat infrequently, I find myself inspecting the elements of the last time I implemented it to refresh my memory.  So, I created a little reference pen with the styling I’ve always used:

There are some more complicated usages of description lists that you can read more about here.

Happy coding!