Web API 0.1

[Introduction](Web API 0.1#introduction)

[CKANAlyze-web available Commands](Web API 0.1#commands)

[Java Model](Web API 0.1#java-model)

[Errors](Web API 0.1#errors)

##Introduction## CKAnalyze-Web offers statistics about a CKAN catalog (having its catalog name), specific statistics for a single CKAN resource (having its catalog name and resource id). In the following document we are going to present the API communication protocol.

Request / Responses

• All requests are GET requests;
• All requests need to be directed to /rest/COMMANDNAME;
• All responses are in APPLICATION/JSON format

---

We suppose to have:

• Catalog name : cn
• Resource ID (CHKAn resource identifier) : rid

Commands##

/stats : Offers catalog statistics

####GET

####Params

    String catalog

####Return Json CatalogStats (see example below). It contains :

• avgColumnCount : float
• avgResourcesFileSize : float
• avgRowCount : float
• avgStringLength : float
• catalogName : string
• colsPerType : {"datatype":[{"count":int,"typeName":string}]}
• stringLengthsDistribution : {"distribution":[{"frequence":float,length:int}]}
• totalColsCount : int
• totalDatasetsCount : int
• totalFileSizeCount : int
• totalResourcesCount : int

####Example Request: /stats?catalog=cn

Response:

{"avgColumnCount":"7.411368015414258","avgResourcesFileSize":"1556293.999036609","avgRowCount":"1570.3911368015415","avgStringLength":"12.543601906537436","catalogName":"cn","colsPerType":{"datatype":[{"count":"1522","typeName":"STRING"},{"count":"1097","typeName":"DATE"}]},"stringLengthsDistribution":{"distribution":[{"frequence":"608137","length":"0"},{"frequence":"88861","length":"1"},{"frequence":"35369","length":"2"}]},"totalColsCount":"7693","totalDatasetsCount":"570","totalFileSizeCount":"1617346608","totalResourcesCount":"2485"}

/resource-stats : Offers single resource statistics

####GET

####Params

    String catalog : string
    String idResource : string

####Return

Json CatalogStats (see example below). It contains : 

• colsPerType : {"datatype":[{"count" : int,"typeName":string]}
• columnCount : int
• fileFormat : string
• fileName : string
• fileSize : int
• resourceId : string
• rowCount : int
• stringLengthAvg : float
• stringLengthsDistribution : {"distribution":[{"frequence":float,length:int}]}
• url : string

####Example Request: /resource-stats?idResource=rid&catalog=cn

Response:

{"colsPerType":{"datatype":[{"count":"1","typeName":"STRING"},{"count":"2","typeName":"DATE"}]},"columnCount":"5","fileFormat":"csv","fileName":"Entrate-per-categoria-2003.csv","fileSize":"2405","resourceId":"rid","rowCount":"21","stringLengthAvg":"64.47619047619048","stringLengthsDistribution":{"distribution":[{"frequence":"608137","length":"0"},{"frequence":"88861","length":"1"},{"frequence":"35369","length":"2"}]},"url":"http://example.it/csv/res.csv"}

/is-available : checks if a specific catalog is available or not

GET

Params:

  catalog : string

####Return

• status : boolean

####Example: Request: /is-available?catalog=cn

Response: {"status":"true"}

/schedule-catalog : schedule a new catalog or checks last update

####GET ####Params:

   catalog : string

####Return

• alreadyScheduled: boolean
• lastProcessed: Java Date string format

---

Java Model

In this paragraph we will present briefly properties of most important ckanalyze-model POJO

enum Types {
    INT, 
    STRING, 
    FLOAT, 
    DATE,
    GEOJSON,
    EMPTY
}

class ResourceStats {
	String resourceId; // ckan-ID
	int rowCount;
	int columnCount;
	double stringLengthAvg;
	String fileName;
	String fileFormat;
	long fileSize;
	String url;
	List<ResourceDatatypeCount> colsPerType;
	List<StringDistribution> stringLengthsDistribution;
}


class CatalogStats {

	String catalogName;
	int totalDatasetsCount;
	int totalResourcesCount;
	long totalColsCount;
	double avgStringLength;
	long totalFileSizeCount;
	double avgColumnCount;
	double avgRowCount;
	List<CatalogDatatypeCount> colsPerType;
	double avgResourcesFileSize;
	List<StringDistribution> stringLengthsDistribution;
}

##Errors## Managed errors are treated as standard output and consists of an HTTP response with code 400.

####Return

• errorDescription: string

In JAVA model errors are expressed using the JSONIZEDException class which contains the field

String errorDescription

Implementing a Jersey client it's easy to map this object to a real JAVA exception and to throw it.