Overview

Spring projects are listed and documented on the spring.io website. We can find there information about releases, samples, support and more.

Spring.io also exposes a RESTful web service under https://api.spring.io/ for fetching and updating Spring Projects Metadata. It uses hypermedia to describe the relationships between resources and to allow navigation between them.

The source of this application is available in the Sagan project.

Media Type

This web service exposes resources with the application/hal+json Media Type. Requests sent to this service should Accept this type, like:

GET / HTTP/1.1
Accept: application/hal+json
Host: api.spring.io

Authentication

This web service is publicly available here: https://api.spring.io/.

Fetching resources using the HTTP GET method is permitted to all clients. Other HTTP verbs like POST, PUT, PATCH and DELETE require authentication.

Authenticated requests should send a GitHub personal access token as basic authentication with the read:org scope enabled. The user associated with this token must be a member of the Spring team on GitHub.

Index Endpoint

The root endpoint of this web service lists the main resources: Projects and Repositories:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 177

{
  "_links" : {
    "projects" : {
      "href" : "https://api.spring.io/projects"
    },
    "repositories" : {
      "href" : "https://api.spring.io/repositories"
    }
  }
}

The links allow you to access other resources:

Relation Description

projects

Link to Project resources

repositories

Link to Repository resources

Projects

Spring Projects are listed on the official projects page. A Spring Project has an official name in the Spring portfolio. Its sources can be found in a git repository. The team in charge of this project will build the sources and release the resulting artifacts in an Artifact Repository.

Some projects are part of a Release train, i.e. a set of project releases that are known to be compatible. Such projects are gathered under an umbrella project (or parent project).

We can GET the full collection of Spring Projects using the "projects" link provided at the root of the service:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1188

{
  "_embedded" : {
    "projects" : [ {
      "name" : "Spring Boot",
      "slug" : "spring-boot",
      "repositoryUrl" : "https://github.com/spring-projects/spring-boot",
      "status" : "ACTIVE",
      "_links" : {
        "releases" : {
          "href" : "https://api.spring.io/projects/spring-boot/releases"
        },
        "generations" : {
          "href" : "https://api.spring.io/projects/spring-boot/generations"
        },
        "self" : {
          "href" : "https://api.spring.io/projects/spring-boot"
        }
      }
    }, {
      "name" : "Spring Data",
      "slug" : "spring-data",
      "repositoryUrl" : "https://github.com/spring-projects/spring-data",
      "status" : "ACTIVE",
      "_links" : {
        "releases" : {
          "href" : "https://api.spring.io/projects/spring-data/releases"
        },
        "generations" : {
          "href" : "https://api.spring.io/projects/spring-data/generations"
        },
        "self" : {
          "href" : "https://api.spring.io/projects/spring-data"
        }
      }
    } ]
  },
  "_links" : {
    "project" : {
      "href" : "https://api.spring.io/projects/{id}",
      "templated" : true
    }
  }
}

We can then fetch an individual project using its "self" link when listed in the full collection, for example for the Spring Boot project:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 444

{
  "name" : "Spring Boot",
  "slug" : "spring-boot",
  "repositoryUrl" : "https://github.com/spring-projects/spring-boot",
  "status" : "ACTIVE",
  "_links" : {
    "releases" : {
      "href" : "https://api.spring.io/projects/spring-boot/releases"
    },
    "generations" : {
      "href" : "https://api.spring.io/projects/spring-boot/generations"
    },
    "self" : {
      "href" : "https://api.spring.io/projects/spring-boot"
    }
  }
}

Response structure

Path Type Description

name

String

Project Name

slug

String

URL-friendly name of the project

repositoryUrl

String

URL for the source repository

status

String

Support status of the project

_links

Object

Links to other resources

Links

Project responses provide links to other related resources:

Relation Description

self

Canonical self link

parent

Link to parent Project, if any

generations

Link to Generations

releases

Link to Releases

Project Support Status

Each Project has an official support status; the goal here is to set expectations about the type of support you can expect from the Spring team:

Incubating

an experiment which might/might no be officially supported in the future.
Active

actively and officially supported by the Spring team.
Community

actively supported by the Spring community with limited involvement from the Spring team.
End Of Life

not supported anymore; there won’t be new releases for this project.

Project Details

Patching project details

Projects can have a body and spring boot configuration which are displayed on the Project Overview page. This endpoint can be used to update either or both of those.

PATCH /projects/spring-boot/details HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 53
Host: api.spring.io

{
  "bootConfig" : "new sbc",
  "body" : "new body"
}
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
This request requires Authentication.

Request structure

Path Type Description

bootConfig

String

Spring Boot Config

body

String

Project Body

Releases

The Project team selects the currently relevant releases; they’re often releases that belong to active Project Generations. We can get the list of releases for a given project by following the "releases" link on the Project resource:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1295

{
  "_embedded" : {
    "releases" : [ {
      "version" : "2.3.0",
      "apiDocUrl" : "https://docs.spring.io/spring-boot/docs/2.3.0/api/",
      "referenceDocUrl" : "https://docs.spring.io/spring-boot/docs/2.3.0/reference/html/",
      "status" : "GENERAL_AVAILABILITY",
      "current" : true,
      "_links" : {
        "repository" : {
          "href" : "https://api.spring.io/repositories/spring-releases"
        },
        "self" : {
          "href" : "https://api.spring.io/projects/spring-boot/releases/2.3.0"
        }
      }
    }, {
      "version" : "2.3.1-SNAPSHOT",
      "apiDocUrl" : "https://docs.spring.io/spring-boot/docs/2.3.1-SNAPSHOT/api/",
      "referenceDocUrl" : "https://docs.spring.io/spring-boot/docs/2.3.1-SNAPSHOT/reference/html/",
      "status" : "SNAPSHOT",
      "current" : false,
      "_links" : {
        "repository" : {
          "href" : "https://api.spring.io/repositories/spring-snapshots"
        },
        "self" : {
          "href" : "https://api.spring.io/projects/spring-boot/releases/2.3.1-SNAPSHOT"
        }
      }
    } ]
  },
  "_links" : {
    "project" : {
      "href" : "https://api.spring.io/projects/spring-boot"
    },
    "current" : {
      "href" : "https://api.spring.io/projects/spring-boot/releases/current"
    }
  }
}

Fetching a single Release

We can fetch a single release by following its canonical link:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 451

{
  "version" : "2.3.0",
  "apiDocUrl" : "https://docs.spring.io/spring-boot/docs/2.3.0/api/",
  "referenceDocUrl" : "https://docs.spring.io/spring-boot/docs/2.3.0/reference/html/",
  "status" : "GENERAL_AVAILABILITY",
  "current" : true,
  "_links" : {
    "repository" : {
      "href" : "https://api.spring.io/repositories/spring-releases"
    },
    "self" : {
      "href" : "https://api.spring.io/projects/spring-boot/releases/2.3.0"
    }
  }
}

Response structure

Path Type Description

version

String

Release Version string

status

String

Status of this Release

referenceDocUrl

String

URL for the reference documentation

apiDocUrl

String

URL for the API documentation

current

Boolean

Whether this release is the most recent, officially supported

_links

Object

Links to other resources

Release version status

SNAPSHOT

Unstable release with limited support; SNAPSHOT versions are released continuously

PRERELEASE

Also known as Milestone, this a release meant to be tested by the community

GENERAL_AVAILABILITY

Release Generally Available on public artifact repositories and getting full support from maintainers

Links

Release responses provide links to other related resources:

Relation Description

self

Canonical self link

repository

Link to the Repository hosting this Release

Adding a new Release

We can add a new Release to a Project:

POST /projects/spring-boot/releases HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json
Content-Length: 211
Host: api.spring.io

{
  "version" : "2.8.0",
  "isAntora" : true,
  "apiDocUrl" : "https://docs.spring.io/spring-boot/docs/{version}/api/",
  "referenceDocUrl" : "https://docs.spring.io/spring-boot/docs/{version}/reference/html/"
}
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Location: https://api.spring.io/projects/spring-boot/releases/2.8.0
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
This request requires Authentication.

Request structure

Path Type Description

version

String

The Release version

isAntora

Boolean

Indicates if the documentation for this release is on Antora. Defaults to false if not specified.

referenceDocUrl

String

URL of the reference documentation, {version} template variable is supported

apiDocUrl

String

URL of the API documentation, {version} template variable is supported

Deleting an existing Release

We can delete an existing Release from a Project:

DELETE /projects/spring-boot/releases/2.3.0 HTTP/1.1
Accept: application/hal+json
Host: api.spring.io
HTTP/1.1 204 No Content
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
This request requires Authentication.

Generations

Each project has an official Support Status, but not all releases are supported at any time. Releases are grouped as Generations. Depending on the project and its release policy, a Generation usually regroups all maintenance Releases for a given minor version or a specific release train.

Developers should upgrade to the latest Release at their earliest convenience; the Spring team helps drive that decision by providing end of support dates for each generation.

Each project generation has two periods of active support: Open Source support and Commercial support. All releases cut during these support periods are publicly available in the artifact repositories.

We can get the list of generations for a given project by following the "generations" link on the Project resource:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 956

{
  "_embedded" : {
    "generations" : [ {
      "name" : "2.2.x",
      "initialReleaseDate" : "2020-02-01",
      "ossSupportEndDate" : "2021-03-31",
      "commercialSupportEndDate" : "2027-03-31",
      "_links" : {
        "self" : {
          "href" : "https://api.spring.io/projects/spring-boot/generations/2.2.x"
        },
        "project" : {
          "href" : "https://api.spring.io/projects/spring-boot"
        }
      }
    }, {
      "name" : "2.1.x",
      "initialReleaseDate" : "2020-01-01",
      "ossSupportEndDate" : "2021-03-01",
      "commercialSupportEndDate" : "2022-03-01",
      "_links" : {
        "self" : {
          "href" : "https://api.spring.io/projects/spring-boot/generations/2.1.x"
        },
        "project" : {
          "href" : "https://api.spring.io/projects/spring-boot"
        }
      }
    } ]
  },
  "_links" : {
    "project" : {
      "href" : "https://api.spring.io/projects/spring-boot"
    }
  }
}

We can of course fetch a single generation by following its canonical link:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 348

{
  "name" : "2.2.x",
  "initialReleaseDate" : "2020-02-01",
  "ossSupportEndDate" : "2021-03-31",
  "commercialSupportEndDate" : "2027-03-31",
  "_links" : {
    "self" : {
      "href" : "https://api.spring.io/projects/spring-boot/generations/2.2.x"
    },
    "project" : {
      "href" : "https://api.spring.io/projects/spring-boot"
    }
  }
}

Response structure

Path Type Description

name

String

Generation Name

initialReleaseDate

String

Date of the first release for this Generation

ossSupportEndDate

String

End date of the OSS support

commercialSupportEndDate

String

End date of the Commercial support

_links

Object

Links to other resources

Artifact Repositories

Releases are hosted on public Artifact Repositories. The Spring team deploys artifacts to different repositories, depending on the Release Status. You can configure your build system to resolve dependencies from the artifact repositories listed by this service. "Generally Available" releases are also available on Maven Central and its mirrors.

Each Project Release has a link to an Artifact Repository resource. You can fetch the full list of repositories managed by the Spring team by following the "repositories" link on the root endpoint:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 939

{
  "_embedded" : {
    "repositories" : [ {
      "identifier" : "spring-snapshots",
      "name" : "Spring Snapshots",
      "url" : "https://repo.spring.io/snapshot",
      "snapshotsEnabled" : true,
      "_links" : {
        "self" : {
          "href" : "https://api.spring.io/repositories/spring-snapshots"
        }
      }
    }, {
      "identifier" : "spring-milestones",
      "name" : "Spring Milestones",
      "url" : "https://repo.spring.io/milestone",
      "snapshotsEnabled" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.spring.io/repositories/spring-milestones"
        }
      }
    }, {
      "identifier" : "spring-releases",
      "name" : "Spring Releases",
      "url" : "https://repo.spring.io/release",
      "snapshotsEnabled" : false,
      "_links" : {
        "self" : {
          "href" : "https://api.spring.io/repositories/spring-releases"
        }
      }
    } ]
  }
}

And get a single repository by following its canonical link:

HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 0
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 251

{
  "identifier" : "spring-releases",
  "name" : "Spring Releases",
  "url" : "https://repo.spring.io/release",
  "snapshotsEnabled" : false,
  "_links" : {
    "self" : {
      "href" : "https://api.spring.io/repositories/spring-releases"
    }
  }
}

Response structure

Path Type Description

identifier

String

Repository Identifier

name

String

Name of the Repository

url

String

URL of the Repository

snapshotsEnabled

Boolean

Whether SNAPSHOT artifacts are hosted on this Repository

_links

Object

Links to other resources

Links

Relation Description

self

Canonical self link