Pre-meeting missive

The main point of this meeting (apart from introducing ourselves) should be a discussion of the Web Service API -- we need to hammer this down so we can get started writing code. Of course, we also need to talk about who's willing to handle what parts of the code (no, you can't all work on the cmdlets).

In order to make that conversation easier to have, we ask that you will all have at least looked over what we have so far on our requirements page Requirements so we can just jump right into anything you see which either needs to change or needs more detail.

In particular, we need to be thinking about :
  1. What data needs to be a part of the API? (author, download url, Cmdlet/Function name(s), what else?)
  2. How we handle different TYPES of code artifacts: Module, Script, Function, Snippet ... do we need to separate the idea of a "sample snippet" out of our main API so that we can make something useful? That is: Should we make a single "function" (or external script -- which is actually treated as a function if it's in your path) the smallest unit of code that we talk about?
  3. What should the WebService API look like? (implementable in any web language: asp.net/wcf/php, easy to consume ... need "search" and "get" commands, what else?)

Don't forget: we're trying to create a WebService API that is easy enough to implement and work with that everyone who considers creating a PowerShell script repository would be motivated to implement it.

Step one in this is to create a sort-of contract for what information is going to have to be in our "PoshCodeInfo" object. Bear in mind that a this object is somewhat like a PSModuleInfo object (the output of Get-Module in CTP2):

PSModuleInfo: PoshCodeInfo
Exports A list of the cmdlets/functions/variables Exports A collection of CommandInfo objects
IsCompiledCode Boolean: yes/no CodeType Script/Compiled/Source
Name The module name Name The name assigned by the uploader
Path The file location Url The link to download from (downloads THIS version?)
Version A Hash: the version number and hash
UpdateUrl The Url to check for new versions (can be the same as the Url)
Date The date of upload
Author UserName or OpenID
Tags A list of tags, including Noun:XXX and Verb:XXX ?


The simplest thing for us would be to just add Date, Author, and URL and call it a day, but we probably want to have a little more information about the cmdlets/functions that are in the module. In CTP2 you can do: Get-Module | Select -Expand Exports | Get-Command ... unless we can think of a way to do that for the Cmdlets that are in a module on our server, we may want to include the information about them in our PoshCodeInfo object -- would we then want to have a separate lighter set of data we return from a search? (lets talk about it tonight -- see the wiki for my current thought).

Other examples of script information you could look at are the objects returned from: gcm * | gm ... particularly CmdletInfo and ExternalScriptInfo.

My feeling right now is that we will want our API to output these "objects" in a relatively human-readable (xml) serialization format which the cmdlets/apps could then re-render as PoshCodeInfo objects ... in my ideal world this would mean that we or others can EXTEND the data in the object later on without breaking applications written against the base API. That said, we would dearly like to get this right the ahem third time around ;-) (that is, this time, for those of you not keeping score).

TO SUM UP:

  1. Think about what the PSModuleInfo object and CmdletInfo object look like. What needs to be added to that so that an end user could figure out whether they want to download the actual script, and how to download it.
  2. Think about how we and end users will store this data, will tags and "machine tags" work? Do you like the idea (as written in the requirements on the wiki) of (mis)using them to store all sorts of extra data -- which might be specific to a given implementation of the service?
  3. How much data do we want send over in search results. What about "dependencies"?
  4. Think about ways to embed the data with the downloaded files!!
    1. PS v2 has a concept of a "data manifest" for modules, but that may already be a part of the uploaded code.
    2. We need to handle this differently for multi-file modules than for scripts -- we need to EMBED the data in the script, whereas a module could have a separate file, since a module gets extracted to it's own folder.
    3. Can we just embed the meta data, in PSD1 format, in a comment block at the top of the file (at the top of the .psd1 file if you upload a module), and have a script/cmdlet which can extract that data and show it to the end user if they ask for information about a script?
  5. Can we design this so that the cmdlets will work with metadata objects in scripts and allow you to check "any" server for a new version?
    1. You could put metadata in a script file you host on your blog that just points to a file on your webserver, or that points to our web-service.
    2. We could serve up metadata in our search results about modules which we don't host (PSCX?) which would tell you what's in them, and where to get them.
    3. PSCX could include our metadata in their PSD1 file, and our cmdlets would be able to check for and optionally download an updated version

Just for today ... lets not talk about script signing at all ;-)

Meeting Notes

Last edited Sep 11, 2008 at 2:52 PM by Jaykul, version 1

Comments

No comments yet.