API v3 Specification

Status

All designs specified should be considered in an early draft state and should not be viewed as final or authoritative. Feedback is highly desired.

Goals

Scenarios to address

1. Can't change the client/server interaction for our clients without also affecting unknown clients

• An example is when we wanted to use Lucene for search
• We need to maintain existing capabilities
• Ability to make targeted server-side changes to aide our clients
  • EX: change search from Odata to Lucene

1. Can't currently pass in arbitrary arguments or filtering or sorting

• We are currently constrained by Odata for our search

1. Reduce risk of unintended regressions
2. Ability to add new logic for new versions of the clent(s) without affecting old clients

• Versionable API by operation

1. Feed source for VS that doesn't contain the API version

• Make the client less bound to specific version URLs

1. Ability to scale the API separately from the Web site (e.g. http://api.nuget.org)
2. Efficient APIs for ecosystem

• Instead of today's "download the world" approach
• Catering replication/mirroring

1. Ability to handle new tasks such as "does this package/version exist?" ala HEAD request for a package
2. Fallback URLs for downloading packages

• Handle CDN blocked scenario

1. Capability to grow into 1:N gallery:feeds by user

• This is the "everything can be a feed" scenario

1. Better transparency for HTTP requests (akin to NPM)
2. Backwards-compatible with old clients and Odata consumers
3. Very little model logic in the client
4. Ability for client to recognize server's API version

• Compatibility with other galleries/feeds

Candidate list of service capabilities

• Get list of services
• Get list of packages
• Search for packages
• Get list of updates for a set of packages
• Get all versions for a package
• Get list of alternate feed sources
• Get all packages for an author
• Get all packages for an owner (or organization)
• push a package
• setup a curated feed
• Get package statistics
• Get announcements (could drive the site homepage)
• Push a new announcement
• Create a new organization
• Register a user
• Authenticate a user
• Get package dependencies
• Update package metadata (specifically thinking of tags here when they are separated from the nupkg file)
• Report abuse
• [New] Contact all dependents
• Unlist (delete) a package
• Add package owner
• Remove package owner
• Show all versions for a package
• Show dependency graph for a version of a package
• [New] follow a package
• [New] Get feed for followed packages for a user
• [New] follow a user's followed packages
• Edit user profile
• Get list of known licenses/license URLs