TBD: we may want to derive all the data used in the SNSD files from Data Types feature (schema).
The basic of SNSD (Snap Software Description) is an XML file that describes various types of software products (libraries, servers, GUI based software, etc.) On a Snap! website a page used to describe a software product can have a link to SNSD meaning that that page represents a file that should appear in the SNSD catalog.
The XML files offered give third party systems a way to quickly learn about all the files that you are offering. The SNSD data can be found on specific pages, in the HTML header, the HTTP header, the robots.txt file, and via the SNSD REST API.
The HTML header makes use of various Data Types schemas. We do not intend to re-invent the wheel for such. Data that cannot be represented in the HTML header is simply not made available there.
The REST API allows one to navigate the comlete list of software offered on a website. If you are one of those websites offering software for download, your entire catalog can appear in the SNSD directory.
The root of the REST API for SNSD can be sepcified in the HTTP header, the HTML header, your robots.txt, or (if none of these were defined) make use of the default URI which is "/snap-software-description.xml", for example for this website it would be:
http://snapwebsites.org/snap-software-description.xml
The REST API can be used to add new software as well, assuming you have the proper credential to do so if required.
The main reason to allow for a full REST API is to allow for software publishers to send a signal to interested websites whenever they post a new version of their software. In other words, the API offers a full pusblish/subscribe mechanism, instead of relying on a poll mechanism as with other similar formats (i.e. PAD Files).
In most cases, publishers want to create accounts of various websites that offer (large) lists of software and enter their credentials in their Snap Software Description aware server. That way the server can automatically send updates when things change.
The SNSD description for a software starts with its XML file format. The XML format describes ONE software, yet it offers the ability to define many variant of the software.
<?xml version="1.0"?>
<snsd-file version="1.0" rest="...url..." publisher="...url.." support="...url..." self="...url...">
<!-- the rest attribute gives the root URI for the REST API -->
<generator>Snap! Websites</generator>
<specification>
http://snapwebsites.org/implementation/feature-requirements/pad-and-snsd-files-feature/snsd-rest-api
</specification>
<technical-name>your_software_technical_name</technical-name>
<link>url</link> <!-- this software project page -->
<description>
<name xml:lang="...">Your Software Name</name>
<icon width="..." height="...">...url...</icon>
<desc45 xml:lang="...">...</desc45>
<desc80 xml:lang="...">...</desc80>
<desc250 xml:lang="...">...</desc250>
<desc450 xml:lang="...">...</desc450>
<desc2000 xml:lang="...">...</desc2000>
<desc xml:lang="...">...</desc>
<!-- unlimited length, can include HTML although it has to be escaped (or in a CDATA section) -->
<screenshot href="...url..." width="..." height="..." xml:lang="...">...</screenshot>
<!-- a URI to a screenshot and an optional description or label for the screenshot, any number of screenshots are allowed -->
</description>
<category type="..." install="...">
<!-- "type" is one of: public domain, freeware, open source, shareware, adware,
demo, commercial, data-only, source -->
<!-- "install" is one of: install-uninstall, install-only, no-install, uninstall-only -->
<class>...</class> <!-- categorization such as Development::C++, Game::Role_Playing_Game... -->
<keywords>...</keywords> <!-- keywords/tags in link with your software -->
</category>
<compatibility>
<os id="..." name="..."> <!-- one of: Microsoft Windows, Apple, Linux, etc. -->
<version distribution="..." since="since">...</version>
<!-- one entry per version supported of that OS,
use "since" boolean flag if all versions after that version are also supported -->
</os>
<language>...</language> <!-- one per human language used in software interface -->
<requirements>...</requirements> <!-- human readable requirements -->
</compatibility>
<license href="...url..."> <!-- URL to a copy of the licence on your site -->
<abstract>...short resume...</abstract>
<verbatim>...verbatim license...</verbatim> <!-- optional -->
<costs currency="...">...</costs>
<expire type="..." count="..." date="..." order="...url...">...description...</expire>
<!-- shareware, demo licenses generally expire after a given set of parameters
type can be "never" (default) -- count and date ignored
"days" -- count is the number of day since installation
"uses" -- count is the number of times the software can be used
"date" -- the fixed date="..." is used
"order" -- a URI to a page where one can order various licenses -->
<distribution-permissions type="..."/>
<!-- type of allowed distributions for this software:
"all" -- can be copied anywhere, modified, etc. (open source)
"copy" -- you are allowed to copy and redistribute
"link" -- you are only allowed to put a link to the source -->
</license>
<release date="YYYYMMDD" status="..." reasons="..." version="..." href="...url...">
<!-- release-date: when version was released -->
<!-- status: "development-started", "alpha", "beta", "production" -->
<!-- reasons: "patch", "new-features", "new-media" -->
<!-- version: the version of this specific release -->
<!-- href: if you have a specific web page for this release -->
<download type="..."> <!-- type: "documentation", "source", "binary", ... -->
<link for="...ref to os id...">...url...</link> <!-- direct link to download your software, can be duplicated for mirrors -->
<size>...byte-size...</size>
</download>
<changelog>...</changelog> <!-- same as changelog file for this specific release -->
</release>
</snsd-file>
The following describes the Publisher XML file:
<?xml version="1.0"?>
<snsd-publisher version="1.0" rest="...url..." self="...url...">
<generator>Snap! Websites</generator>
<specification>
http://snapwebsites.org/implementation/feature-requirements/pad-and-snsd-files-feature/snsd-rest-api
</specification>
<publisher>
<company-name>Your Company Name</company-name>
<publisher-name>Your Name</publisher-name>
<website>url</website> <!-- a URI to your website -->
<support>url</support> <!-- a URI to your website support page -->
<street-address1>123 1st Street</street-address1>
<street-address2>Suite #1</street-address2>
<city>Your City</city>
<province>Your State/Province</province> <!-- only if defined in an address -->
<postal-code>Your Location Postal Code</postal-code>
<country>Your Country</country>
<phone>Your Phone</phone>
<fax>Your Fax</fax>
<email>Your Email</email>
<feed-company>...url...</feed-company>
<feed-product>...url...</feed-product>
</publisher>
</snsd-publisher>
The <generator> tag is the name of the software that generated this XML file.
The <specification> tag is the URL to this specification.
The <publisher> tag defines the author or owner of the software. This is often the name of a person for small software and the name of a company for a large software.
The <company-name> tag defines the name of the company that created this software.
The <publisher-name> tag defines the name of a person who wrote this software.
The <website> tag defines a URL to the website describing the software publisher. This may be your resume or the company About Us page.
The <support> tag defines the URL to a support page. That support page will usually also include a Snap! Software Description file as decribed in the Support section.
The <streeet-address1/2> tags define the street name (1) and optional suite (2) of your real physical address, in case you have a public office where people can come by and ask for support.
The <city>, <province>, <postal-code>, and <country> tags are also for the physical address definition. You should include the name of the city if you offered the street address. The other tags are optional.
The <phone> and <fax> tags are for phone numbers that can be used to contact you for support. If you are a larger organization, you may want to enter the phone number for support, specifically. The publisher XML file also includes a phone number which can be a sales phone number.
The <email> tag is expected to be a valid email address that one can use to contact you for support of your software. It does not need to be a personal email address (i.e. something like support@m2osw.com would work too.)
The <feed-company> tag is a URL to an RSS or Atom feed, which is in link with the publisher. In general, that would be your News Feed. It may be about anything that your company offers.
The <feed-product> tag is a URL to an RSS or Atom feed, which is showing posts about your products. This feed can be sales oriented. It may also include various broad support information and security information (i.e. when you should upgrade the software to keep it secure.)
The following describes the Support XML file. If you create a support page, this XML file can be attached to that page.
<?xml version="1.0"?>
<snsd-support version="1.0" rest="...url..." self="...url...">
<generator>Snap! Websites</generator>
<specification>
http://snapwebsites.org/implementation/feature-requirements/pad-and-snsd-files-feature/snsd-rest-api
</specification>
<support>
<contact-name>Your Name</contact-name>
<website>url</website> <!-- a direct URI to your support page -->
<street-address1>123 1st Street</street-address1>
<street-address2>Suite #1</street-address2>
<city>Your City</city>
<province>Your State/Province</province> <!-- only if defined in an address -->
<postal-code>Your Location Postal Code</postal-code>
<country>Your Country</country>
<phone>Your Phone</phone>
<fax>Your Fax</fax>
<email>Your Email</email>
<feed-support>...url...</feed-support>
</support>
</snsd-support>
The <generator> tag is the name of the software that generated this XML file.
The <specification> tag is the URL to this specification.
The <support> tag defines how the software is supported. The support information is optional. It is indicated on a per software basis since you may offer many different software on one website each of which has a different support policy.
The <contact-name> tag defines the name of a person who should be contacted whenever there is a problem with the software. If you have many support people, then you may want to not enter that information.
The <website> tag gives the user a URL where there is more information about how to get support for the software. For a greater chance to get support requests, it should be a link to either a well known website (like stackoverflow) or the site were your software is generally available.
The <streeet-address1/2> tags define the street name (1) and optional suite (2) of your real physical address, in case you have a public office where people can come by and ask for support.
The <city>, <province>, <postal-code>, and <country> tags are also for the physical address definition. You should include the name of the city if you offered the street address. The other tags are optional.
The <phone> and <fax> tags are for phone numbers that can be used to contact you for support. If you are a larger organization, you may want to enter the phone number for support, specifically. The publisher XML file also includes a phone number which can be a sales phone number.
The <email> tag is expected to be a valid email address that one can use to contact you for support of your software. It does not need to be a personal email address (i.e. something like support@m2osw.com would work too.)
The <feed-support> tag is a URL to an RSS or Atom feed, which is in link with support. For example, if you write posts on something that looks like a blog, you can provide the feed of that blog. It should be limited to support (i.e. do not include sales posts in those feeds, users who read them will already have bought your product.)
The following is what the REST API returns when reading a directory for SNSD files starting from the root:
<?xml version="1.0"?>
<snsd-catalog version="1.0" rest="...url..." self="...url...">
<generator>Snap! Websites</generator>
<specification>
http://snapwebsites.org/implementation/feature-requirements/pad-and-snsd-files-feature/snsd-rest-api
</specification>
<toc>url</toc> <!-- a URI to an HTML table of content (human readable) -->
<file>url</file> <!-- a URI to an SNSD file, can be repeated -->
<catalog category="...">url</catalog> <!-- a sub-catalog for that category of files, can be repeated -->
</snsd-catalog>
The <generator> tag is the name of the software that generated this XML file.
The <specification> tag is the URL to this specification.
The <toc> tag is a URL to a page where users can start browsing your software. This is often the home page of your website. If your home page is not exactly a browsing capable page, then you probably want to give a better page. For example, if you have the e-Commerce plugin installed, you may want to specific the URL to the /product page. With Snap! Websites, the page is marked with a link. Until such a link exists, no <toc> tag is created.
The <file> tag, which can be repeated, defines the URL to a page representing a software. That page will have all the necessary definitions to generate an <snsd-file> XML file. Only files that are not categorized are added in a <file> tag of the root. Categorized files only appear in sub-<catalog>s. Categories should be used on a site that has many files (i.e. more than 100 or so.)
The <catalog> tag, which is repeated for each category, defines the URL to a page used as a catalog tag. The category attribute, which is mandatory, represents a category type under the taxonomy: /types/snap-software-description/<category-name>.
This specification adds one new HTML Header to allow finding the SNSD file without having to test whether it exists. The header makes use of a link tag:
<link name="snap-software-description" type="application/xml" title="Snap Software Description"
rel="alternate" href="..."/>
The HREF points to the SNSD XML file. By default, the root is right under your domain name: http://www.example.com/snap-software-description.xml
TBD: Should we also have an alternate link for the publisher and support files? Since these can be found from the snsd file, it probabl isn't required.
TODO: Find fields in the schema that would fit with the software description. See Meta Tags and Links supported by Core
The HTML header can include a link to the REST API of the Snap Software Description as in:
<link name="snsd-rest" type="application/xml" title="Snap Software Description REST API"
rel="alternate" href="..."/>
Here we send machines to our XML REST application. You may want to limit these links to only pages where you have a software description and your home page.
The HTTP header also gives us the SNSD file URI, just like the HTML Header.
This is a single field which gives the REST API:
X-Snap-Software-Description: http://...
This is only the link to the REST API and not the link to a software. You may want to limit these links to only pages where you have a sotware description and your home page.
The robots.txt file can include a link to the REST API of the SNSD support:
Snap-Software-Description: http://...
It looks very much the same as the HTTP header. However, this avoids duplication since it appears in a single file instead of many HTTP requests.
The REST API allows machines to query your website to find a list of Snap Software Description files. This means the REST API helps in finding the list of such files. A full implementation also allows you to add new entries and delete existing entries in your list of software descriptions.
To retrieve the top level catalog, use the GET command with the URI specified in the HTTP header, HTML header, or robots.txt file:
GET http://...
This returns an XML file (see snds-catalog). Depending on the website, the XML may include all the software (small website) or only a list of categorized software (large website).
You cannot create the root catalog. It has to be offered by the server. (The server may offer a different API to allow such creation.)
When checking out the data, you can simply use a GET and these do not generally require authorization (in most cases you want your software offering to be public.)
All other operations require an Authorization HTTP field. This field includes your authentication name and secret separated by a colon and the result is encoded using Base64. Those credentials are generally given to you by a system where you register an account. That way these credentials can be quite large. This helps against brutal force hacking.
Authorization: Basic "Base64 of Username:Password"
For added security, the client and server should probably always make use of TLS. Sending a request to a resource that requires it without that Authorization field, the server is expected to return a 403 error (i.e. forbidden) although the server can also return a 401 error to challenge the client.
The session generation may fail for other reasons too and return other codes such as 402 (payment required--the account funds were drained) or 409 (conflict--maybe the server does not allow more than one log in at a time).
Using a POST, you can add a catalog. (Future versions may actually allow you to use the PUT instruction to add a catalog and any number of files all at once. At this time, we only offer the adding of a catalog.)
In this case, the POST must be to an existing catalog. The new catalog will appear as a child of the main catalog. This POST makes use of one variable: category, which is to be set to a valid category name. In most cases, adding something to an SNSD server requires credential. In that case, the POST must also include an Authorization field.
POST http://... Authorization: ... category=<name>
It is possible to delete sub-catalogs that were previously created with a POST command.
By default the deletion is not recursive. If you set the recursive flag to true, then everything gets deleted. With the default or the flag set to false, the deletion fails if there is one or more files or sub-catalogs defined in this catalog. Servers are not required to support the recursive flag. The catalog to delete is defined using its category. In that case, the DELETE must also include an Authorization field.
DELETE http://... Authorization: ... category=<name> recursive=false
If the delete succeeds, the server returns a 204 code (No Content).
Using a POST, you can add a software specification. Note that does not in any way give you a way to upload the actual software, only to add descriptions.
You have to POST to a catalog. By default, that means the root catalog as defined first above. If you create sub-catalogs, then you can post to any one of them. The POST generally requires credentials so you may include a session variable too. Note that the POST has to be constructed as a multi-part attachment, the XML file being one of the entries. In that case, the POST must also include an Authorization field.
# WARNING: This is wrong, it has to be a multi-part attachment, will fix sample later. POST http://... Authorization: ... file=<xml file> # This really uses a multi-part attachment and not a simple parameter list
Removing a software is possible with the DELETE command. It is done by specifying the software URI. In that case, the DELETE must also include an Authorization field.
DELETE http://... Authorization: ...
If the delete succeeds, the server returns a 204 code (No Content).
Snap! Websites
An Open Source CMS System in C++
