API endpoints for Maven projects

ToC

• Getting started
• Endpoints
  • Packages and package versions
  • Dependencies
  • Modules
  • Binary Modules
  • Callables
  • Edges
  • Files
  • Resolution
  • Vulnerabilities
  • Stitching/Integration
• Lazy ingestion

Getting started

Take a look at the documentation to see how to launch the REST server.

Endpoints

Packages and package versions

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/mvn/packages	GET	—	limit: integer, offset: integer	200: Packages returned 400: Invalid limit value 400: Invalid offset value 404: Package not found	{ "id": bigint, "package_name": text, "forge": text, "project_name": text, "repository": text, "created_at": timestamp, "version": text } Search packages
✅ Missing: tests	/mvn/packages/search	GET	—	packageName: text, limit: integer, offset: integer	200: Packages returned 400: Invalid limit value 400: Invalid offset value	[ { "id": bigint, "package_name": text, "forge": text, "project_name": text, "repository": text, "created_at": timestamp } ] All packages
✅ Missing: tests	/mvn/packages/{pkg}	GET	—	—	200: Package returned	[ { "id": bigint, "package_name": text, "forge": text, "project_name": text, "repository": text, "created_at": timestamp } ] One package with its latest version number.
✅ Missing: tests	/mvn/packages/{pkg}/versions	GET	—	limit: integer, offset: integer	200: Package versions returned 400: Invalid limit value 400: Invalid offset value 404: Package not found	[ { "id": bigint, "package_id": bigint, "version": text, "cg_generator": text, "created_at": timestamp, "metadata": json } ]
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	{ "id": bigint, "package_id": bigint, "version": text, "cg_generator": text, "created_at": timestamp, "metadata": json }
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/metadata	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	{ "package_name": text, "version": text, "metadata": json }
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/callgraph	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	[ { "source_id": bigint, "target_id": bigint } ] Could be retrieved directly from graph DB.
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/rcg	GET	—	artifactRepository: text, releaseDate: long	200: OK	"link to JSON RCG for downloading"
✅ Missing: tests	/mvn/package_version/{pkg_version_id}/rcg	GET	—	—	200: OK	"link to JSON RCG for downloading"

Dependencies

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/deps	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	[ { "package_version_id": bigint, "dependency_id": bigint, "version_range": [ text ], "metadata": json } ]

Modules

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/modules	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	[ { "id": bigint, "package_version_id": binint, "namespace": text, "created_at": timestamp, "metadata": json } ]
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/modules/metadata	POST	"module namespace"	artifactRepository: text, releaseDate: long	200: OK 404: Module namespace not found	[ { "package_name": text, "version": text, "namespace": text, "metadata": json } ]
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/modules/files	POST	"module namespace"	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found 404: Module namespace not found	[ { "id": bigint, "package_version_id": bigint, "path": text, "checksum": bytea, "created_at": timestamp, "metadata": json } ]
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/modules/callables	GET	"module namespace"	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found 404: Module namespace not found	[ { "id": bigint, "module_id": bigint, "fasten_uri": text, "is_internal_call": boolean, "created_at": timestamp, "line_start": int, "line_end": int, "metadata": json } ]

Binary Modules

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅:warning: Not tested due to missing data in KB. Also Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/binary-modules	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	[ { "package_name": text, "version": text, "name": text, "metadata": json } ]
✅:warning: Not tested due to missing data in KB. Also Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/binary-modules/{binary_module}/metadata	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found 404: Binary name not found	[ { "package_name": text, "version": text, "name": text, "metadata": json } ]
✅:warning: Not tested due to missing data in KB. Also Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/binary-modules/{binary}/files	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found 404: Binary name not found	[ { "id": bigint, "package_version_id": bigint, "path": text, "checksum": bytea, "created_at": timestamp, "metadata": json } ]

Callables

Callable ID = module ID (package version) + FASTEN URI

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/callables	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	[ { "id": bigint, "module_id": bigint, "fasten_uri": text, "is_internal_call": boolean, "created_at": timestamp, "line_start": int, "line_end": int, "metadata": json } ]
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/callable/metadata	POST	"fasten uri"	artifactRepository: text, releaseDate: long	200: OK 404: Package not found 404: Package version not found 404: FASTEN URI not found	{ "package_name": text, "version": text, "fasten_uri": text, "metadata": json }
✅ Missing: tests	/callables	POST	List of fully qualified FASTEN URIs	—	200: OK	{ "": metadata:json, "": metadata:json, ... }

Edges

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/edges	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	[ { "source_id": bigint, "target_id": bigint, "receivers": [ { "line": int, "type": text, "receiver_uri": text } ], "metadata": json } ]

Files

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/files	GET	—	limit: integer, offset: integer, artifactRepository: text, releaseDate: long	200: OK 400: Invalid limit value 400: Invalid offset value 404: Package not found 404: Package version not found	[ { "id": bigint, "package_version_id": bigint, "path": text, "checksum": bytea, "created_at": timestamp, "metadata": json } ]

Resolution

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/resolve/dependencies	GET	—	transitive: boolean, timestamp: long	200: OK 404: Package not found 404: Package version not found	[ { "id": bigint "artifactId": text, "groupId": text, "version": text, "createdAt": timestamp, "url": text } ]
✅ Missing: tests	/mvn/packages/{pkg}/{pkg_ver}/resolve/dependents	GET	—	transitive: boolean, timestamp: long	200: OK 404: Package not found 404: Package version not found	[ { "id": bigint "artifactId": text, "groupId": text, "version": text, "createdAt": timestamp, "url": text } ]

Vulnerabilities

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/vulnerabilities	GET	—	limit: integer, offset: integer, attributes:list:text	200: OK	[ { "id": BIGINT, "external_id": TEXT, "statement": JSON //if attributes provided, includes only listed fields } ]
✅ Missing: tests	/vulnerabilities/{external_id}	GET	—	attributes:list:text	200: OK	{ "id": BIGINT, "external_id": TEXT, "statement": JSON //if attributes provided, includes only listed fields }
✅ Missing: tests	/vulnerabilities/{external_id}/purls	GET	—	limit: integer, offset: integer	200: OK	[{ "vulnerability_id": BIGINT "purl": TEXT, "package_name": TEXT, "package_version": TEXT, "forge": TEXT }]
✅ Missing: tests	/vulnerabilities/{external_id}/callables	GET	—	limit: integer, offset: integer	200: OK	[{ "fasten_uri": TEXT, "callable_id": BIGINT }]
✅ Missing: tests	/vulnerabilities/coordinates	POST	List of Maven coordinates	attributes:list:text	200: OK	[{ "$coordinate":"[{ "id": BIGINT, "external_id": TEXT, "statement": JSON //if attributes provided, includes only listed fields }]" }]
✅ Missing: tests	/packages/{pkg}/{pkg_version}/vulnerabilities	GET	—	limit: integer, offset: integer, attributes:list:text	200: OK	[ { "id": BIGINT, "external_id": TEXT, "statement": JSON //if attributes provided, includes only listed fields } ]

Stitching/Integration

Done	Resource	Method	Req. body	Query params	Response codes	Response body
✅ Missing: tests	/callable_uris	POST	List of GIDs (callable IDs)	—	200: OK	{ "gid1": full_fasten_uri:text, "gid2": full_fasten_uri:text, ... }
✅ Missing: tests	/metadata/callables	POST	List of full FASTEN URIs	allAttributes: boolean, attributes: list:text	200: OK	{ "fasten_uri1": callable_metadata:json, "fasten_uri2": callable_metadata:json, ... }
✅ Missing: tests	/resolve_dependencies	POST	List of Maven coordinates (dependencies)	—	200: OK	{ "nodes": [ node_id:bigint ], "edges": [ [ source_id:bigint, target_id:bigint ], ... ] }
✅ Missing: tests	/__INTERNAL__/packages/{pkg_version_id}/directedgraph	GET	—	needStitching: boolean, timestamp: long	200: OK	{ "nodes": [ node_id:bigint ], "edges": [ [ source_id:bigint, target_id:bigint ], ... ] }
✅ Missing: tests	/__INTERNAL__/packages/{pkg}/{pkg_ver}/vulnerabilities	GET	—	precise: boolean	200: OK	{ "": [ {"id": , "fasten_uri": ""}, ... ], "vulnerability2": [...] }
✅ Missing: tests	/__INTERNAL__/ingest/batch	POST	[ { "groupId": "...", "artifactId": "...", "version": "...:, "artifactRepository": "...", // Optional! Default is Maven Central repository "releaseDate": 1417709863000 // Optional! POMAnalyzer will try to automatically find the release date if not provided } ]	-	200: OK	-

Lazy ingestion

Every endpoint that has {pkg}/{pkg_version} in the URL also support the lazy ingestion. This means that if the requested artifact is not found in the database, this artifact will be added to the processing queue i.e. the pipeline input.

Workflow example

When sending the request to the following URL for the first time GET /mvn/packages/junit:junit/4.12, the artifact will not be found and 201 CREATED will be sent as a response. Later, when the processing have completed, sending the same request will result in successfully obtaining the requested information (200 OK). However, before ingesting the artifact, it is checked for existence in the given artifact repository (or default repository - Maven Central). If the artifact is not found there, the user might have mistyped the artifact's name or repository, therefore a 400 BAD REQUEST response is returned.

Different artifact repositories

Lazy ingestion also supports retrieving artifacts from repositories other than Maven Central. Each lazy ingestion endpoint has optional artifactRepository request parameter. Your artifact repository base URL must be passed there.

Example: GET /mvn/packages/android.arch.code:common/1.1.1?artifactRepository=https://dl.google.com/android/maven2/

If artifactRepository is not specified then it is assumed to have the default value of Maven Central Repository (https://repo.maven.apache.org/maven2/).

Also, if the release date of the artifact is known, it can be passed to the same request as another optional parameter releaseDate: long. If releaseDate is not specified then POMAnalyzer will try to automatically retrieve it from the artifact repository by looking at the Last-Modified header of the POM file.