Change Management REST API Specification (Future Concepts)

(Concepts to consider to future specification work)

SPECIFICATION NOTES: This document is intented to capture REST API concepts that will not be part of the initial core services. The intent is to keep the specifications as simple as possible, expanding on the needs as user stories support it.

Introduction

Change Management resources define the change requests, activities and tasks of the software delivery lifecycle. They represent individual change requests, activities and tasks, along with their relationships to other shared resource types such as project, category, release and plan. The intent of this specification is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response codes, mime type handling and resource formats.

Overview of Resource URIs and Methods

Working with Collections

Needs specification

Elaborate on these sub-topics:

• search and query parameters
• format requested: XML, HTML, JSON
• feeds

Getting a Resource

Needs specification

Elaborate on these sub-topics:

• Formats supported: XML, HTML, JSON, etc
• Requesting formats: Accept header, parameter
• Inline content vs. references

Creating New Resources

Needs specification

Elaborate on these sub-topics:

• Resource definition discovery: what elements are needed to be supplied?
• Error handling: constraints aren't satisfied, missing depedent fields, etc?

Updating Resources

Needs specification

Elaborate on these sub-topices:

• Typical CM tools support actions on resources, how do these surface?
• Communicating the workflow model of resources: accept task, resolve, close, duplicate, promote to next state, etc
• Requesting forms directly: no-frames, HTML
• Error handling: responses that can be consumable by tools (and humans)

Deleting Resources

Typically this is thought of as marking a resource as being inactive or deleted.

Needs specification

Resource Formats

See OSLC CM resource definition specification? .

References

• OSLC CM Use Cases & Scenarios
• Jazz Resource Oriented Work Items
• Jazz Data Transfer Objects (DTOs)

-- SteveSpeicher - 02 Dec 2008