Agent Integration: API Version 2.4.1

Version Release Date: 08-Oct-2017

Abstract

Sending contents of a scan should be sent via a simple HTTPS POST request to this url:

https://saas.whitesourcesoftware.com/agent

WhiteSource's API is open source and hosted on GitHub:

https://github.com/whitesource/agents/tree/release-tag-2.4.1

Update Request

The object representing the request is UpdateInventoryRequest.

Headers

Content-Type: application/x-www-form-urlencoded
Charset: utf-8

Body

The body is made up of key-value pairs, it should look like this:

type=UPDATE&agent=generic&agentVersion=2.4.1&pluginVersion=1.0&token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&timeStamp=123&requesterEmail=john.doe@email.com&diff=[
   {
     "projectToken":"yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
     "coordinates":{
       "artifactId":"My Awesome Project",
       "version":"1.0.0"
     },
     "dependencies":[
       {
         "artifactId": "antlr-2.7.7.jar",
         "sha1": "83cd2cd674a217ade95a4bb83a8a14f351f48bd0",
         "otherPlatformSha1": "5976bf31f2183886231da17c633df9d8035d517a",
         "systemPath": "/lib/jars/antlr-2.7.7.jar",
         "children": [],
         "checksums": {
           "SHA1": "83cd2cd674a217ade95a4bb83a8a14f351f48bd0",
           "SHA1_OTHER_PLATFORM": "5976bf31f2183886231da17c633df9d8035d517a"
         }
       }
     ]
   }
]

Breakdown of all request parameters

Parameter Name	Description	Required
type	Type of the WhiteSource request, can be either "UPDATE" or "CHECK_POLICY_COMPLIANCE"	Yes
agent	Type of agent or plugin sending the request to WhiteSource, use "generic" (all lowercase) for now, until we create a unique string to identify your requests	Yes
agentVersion	Version of the agent's API, use the latest = "2.4.1"	Yes
pluginVersion	Version of the plugin you’re developing	Yes
token	Organization API Key found in the Integration API page	Yes
product	Name or token of the product to be matched to in WhiteSource	No
productVersion	Version of the product above, this can be used to maintain different versions of the same product	No
timestamp	Current time in milliseconds	Yes
requesterEmail	Email of the person requesting the libraries for the given projects, must be an email registered with WhiteSource	No
diff	The actual data regarding the projects and dependencies, it's a JSON array of AgentProjectInfo objects Best practice is to create an object with the same fields and then convert it to JSON	Yes

Example I

Example of a simple request (the diff parameter value):

[
	{
	    "projectToken":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
		"coordinates":{
       		"artifactId":"My Awesome Project",
       		"version":"1.0.0"
     	},
     	"dependencies":[
       	{
        	"artifactId": "antlr-2.7.7.jar",
         	"sha1": "83cd2cd674a217ade95a4bb83a8a14f351f48bd0",
         	"systemPath": "/lib/jars/antlr-2.7.7.jar",
        	"checksums": {
	        	"SHA1": "83cd2cd674a217ade95a4bb83a8a14f351f48bd0"
        	}
       	},
       	{
         	"artifactId": "aopalliance-1.0.jar",
         	"sha1": "0235ba8b489512805ac13a8f9ea77a1ca5ebe3e8",
         	"systemPath": "lib/jars/aopalliance-1.0.jar",
         	"checksums": {
         		"SHA1": "0235ba8b489512805ac13a8f9ea77a1ca5ebe3e8"
			}
         }
     ]
   }
]

Note: The entire body is URL encoded.

Example II

Example of a request containing 2 projects with dependency hierarchy (maven plugin):

[
	{
    	"projectToken":"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
		"coordinates": {
    		"groupId": "com.wss",
        	"artifactId": "search-engine-client",
	     	"version": "1.0.0"
    	},
		"parentCoordinates": {
	        "groupId": "com.wss",
	        "artifactId": "search-engine-parent",
	        "version": "1.0.0"
	    },
	    "dependencies":[
	    {
          	"groupId": "org.restlet.jee",
          	"artifactId": "org.restlet.ext.jackson",
          	"version": "2.3.4",
          	"type": "jar",
          	"scope": "compile",
          	"sha1": "336134b649e0dfd7ef0f85d4c0de216b5b0df21a",
          	"systemPath": "C:\\Users\\User\\.m2\\repository\\org\\restlet\\jee\\org.restlet.ext.jackson\\2.3.4\\org.restlet.ext.jackson-2.3.4.jar",
			"filename":"org.restlet.ext.jackson-2.3.4.jar",
			"dependencyType": "MAVEN",
			"checksums": {
         		"SHA1": "336134b649e0dfd7ef0f85d4c0de216b5b0df21a"
			}
          	"children": [
            {
              	"groupId": "com.fasterxml.jackson.core",
              	"artifactId": "jackson-core",
              	"version": "2.4.4",
              	"type": "jar",
              	"scope": "compile",
              	"sha1": "c5cd3347c0a86d0dcfbf3da593d8431d5a789d54",
              	"systemPath": "C:\\Users\\User\\.m2\\repository\\com\\fasterxml\\jackson\\core\\jackson-core\\2.4.4\\jackson-core-2.4.4.jar",
              	"filename": "jackson-core-2.4.4.jar",
              	"dependencyType": "MAVEN",
				"checksums": {
         			"SHA1": "c5cd3347c0a86d0dcfbf3da593d8431d5a789d54"
				}
            },
            {
              	"groupId": "com.fasterxml.jackson.core",
              	"artifactId": "jackson-annotations",
	            "version": "2.4.4",
	            "type": "jar",
	            "scope": "compile",
	            "sha1": "d3dad1a494f94579fca4b6a1142fb15fb68f0b2f",
	            "systemPath": "C:\\Users\\User\\.m2\\repository\\com\\fasterxml\\jackson\\core\\jackson-annotations\\2.4.4\\jackson-annotations-2.4.4.jar",
	            "filename": "jackson-annotations-2.4.4.jar",
	            "dependencyType": "MAVEN",
				"checksums": {
         			"SHA1": "d3dad1a494f94579fca4b6a1142fb15fb68f0b2f"
				}
            }
    	]
   	},
	{
	    "projectToken":"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    	"coordinates": {
    		"groupId": "com.wss",
        	"artifactId": "search-engine-server",
	     	"version": "1.0.0"
    	},
		"parentCoordinates": {
	        "groupId": "com.wss",
	        "artifactId": "search-engine-parent",
	        "version": "1.0.0"
	    },
	    "dependencies":[
	    {
          	"groupId": "xom",
          	"artifactId": "xom",
          	"version": "1.2.5",
          	"type": "jar",
          	"scope": "compile",
          	"sha1": "4166493b9f04e91b858ba4150b28b4d197f8f8ea",
          	"systemPath": "C:\\Users\\User\\.m2\\repository\\xom\\xom\\1.2.5\\xom-1.2.5.jar",
			"filename":"xom-1.2.5.jar",
			"dependencyType": "MAVEN",
			"checksums": {
         		"SHA1": "4166493b9f04e91b858ba4150b28b4d197f8f8ea"
			}
          	"children": [
            {
              	"groupId": "xml-apis",
              	"artifactId": "xml-apis",
              	"version": "1.3.03",
              	"type": "jar",
              	"scope": "compile",
              	"sha1": "3845d5aabd62dc1954f2c0e84a799068c917ad2b",
              	"systemPath": "C:\\Users\\User\\.m2\\repository\\xml-apis\\xml-apis\\1.3.03\\xml-apis-1.3.03.jar",
              	"filename": "xml-apis-1.3.03.jar",
              	"dependencyType": "MAVEN",
				"checksums": {
         			"SHA1": "3845d5aabd62dc1954f2c0e84a799068c917ad2b"
				}
            }
    	]
   	}
]

Breakdown of objects and fields

AgentProjectInfo

Represents a single project, object can be found here: https://github.com/whitesource/agents/blob/master/wss-agent-api/src/main/java/org/whitesource/agent/api/model/AgentProjectInfo.java

Field Name	Description	Required
coordinates	An object containing identifying information about the project	No, unless projectToken isn't provided
projectToken	API Token of the project	No, unless coordinates isn't provided
dependencies	An array of dependencies, each representing a single dependency (library / file) found during the scan	Yes
parentCoordinates	Coordinates of the project's parent project	No

Coordinates

Represents the coordinates of a project, object can be found here: https://github.com/whitesource/agents/blob/master/wss-agent-api/src/main/java/org/whitesource/agent/api/model/Coordinates.java

Field Name	Description	Required
artifactId	Name or artifactId of the project	Yes
version	Version of the project	No
groupId	The groupId of the project	No

DependencyInfo

Represents a project's dependency, object can be found here: https://github.com/whitesource/agents/blob/master/wss-agent-api/src/main/java/org/whitesource/agent/api/model/DependencyInfo.java

Field Name	Description	Required
artifactId	Filename or Maven artifactId of the dependency	Yes
filename	Filename of the file	No, it's recommended to use both artifactId and filename
version	Version of the dependency	No, this is only necessary for a build tool dependency (for example, Maven dependency) and not a simple file
groupId	groupId of the dependency	No, this is only necessary for a build tool dependency (for example, Maven dependency) and not a simple file
sha1	SHA-1 checksum of the file	No, in case where there is no SHA-1, for example NPM package that is found within a package.json file
systemPath	Path of the file on your local machine	No
type	Type of the dependency (only relevant for Maven)	No
scope	Scope of the dependency (only relevant for Maven)	No
classifier	Classifier of the dependency (only relevant for Maven if applicable)	No
dependencyType	representing the type of the dependency, see DependencyType The dependencyType field is used to improve identification of certain dependencies, can be one of: MAVEN GRADLE NPM BOWER GRUNT PYTHON RUBY NUGET RPM DEBIAN	No, but recommended when sending dependencies identified in a non-standard way. For example in a package.json file (NPM) or scanned as an installed RPM package via querying the package manager
checksums	A map of checksumType and the actual checksum values, see ChecksumType The checksums map will be used in future versions to hold all calculated checksums in a single object instead of in separate fields, the checksumType can be one of: SHA1 - sha1 of a file without any manipulations SHA1_OTHER_PLATFORM - sha1 of a file after replacing all new line characters with those an alternate operating system (for example, if in Windows all \r\n (CRLF) will be replaced with \n and vice versa) SHA1_SUPER_HASH - sha1 of a file after removing all whitespaces and new lines SHA1_SUPER_HASH_MSB - sha1 of the top portion of a file after removing all whitespaces and new lines SHA1_SUPER_HASH_LSB - sha1 of the top portion of a file after removing all whitespaces and new lines SHA1_NO_HEADER - sha1 of a file after removing all header comments SHA1_NO_HEADER_SUPER_HASH - sha1 of the top portion of a file after removing all header comants, whitespaces and new lines SHA1_NO_COMMENTS - sha1 of a file after removing all comments (only for JavaScript) SHA1_NO_COMMENTS_SUPER_HASH - sha1 of a file after removing all comments, whitespaces and new lines (only for JavaScript) SHA1_UTF8 - sha1 of a file after encoding in UTF-8 charset MD5 - md5 of a file without any manipukations	Yes, in case you plan on sending more than the standard sha1 checksum In the future we plan on deprecating the 'sha1' field, so please make sure to populate both 'sha1' field and the SHA1 checksumType in the checksums map
children	An array of DependencyInfo objects which are considered transitive dependencies	No

Update Result

The object representing the result is ResultEnvelope.

It contains the name of the organization, and two collections containing the names of the projects that were created and updated.

Example

Here’s an output of the response received from the WhiteSource server:

{
  "envelopeVersion": "2.1.0",
  "status": 1,
  "message": "ok",
  "data": "{
     \"updatedProjects\":[\"My Awesome Project\"],
     \"createdProjects\":[],
     \"organization\":\"Degabit\",
     \"requestToken\":\"6d3eab69-8908-436c-8e08-b8d670f590b0\"
  }"
}

Breakdown of all fields

Parameter Name	Type	Description
envelopeVersion	String	Version of the response structure
status	int	Status code of the operation, can be one of 1 - Success 2 - Bad request format 3 - Server error
message	String	Human readable message, can be one of Status 1 - "ok" Status 2 - "Illegal arguments" Status 3 - "Server error"
data	JSON String	Data of the result that changes according to the result statis. When status is '1' it will contain a JSON representation of an UpdateInventoryResult object (see fields below) When statis is '2' or '3' it will contain an more detaild error message

The 'data' field contains a JSON encoded string which is a serialized UpdateInventoryResult object, it looks like this:

{
     "updatedProjects":["My Awesome Project"],
     "createdProjects":[],
     "organization":"Degabit",
     "requestToken":"6d3eab69-8908-436c-8e08-b8d670f590b0"
}

Breakdown of all data JSON fields

Parameter Name	Type	Description
updatedProjects	String[]	Names of the existing projects that were updated during the update process
createdProjects	String[]	Names of the projects created during the update process
organization	String	Name of the organization
requestToken	String	A token which produced after each plugin update request * Used for troubleshooting cases and record plugin usage logs