problem-domain.asciidoc

Class Scheduling Problem Domain

A domain vocabulary for scheduling classes.

Date	January 2013
Author	Mike Amundsen, Principal API Architect for Layer 7 Technologies
Status	Version 1.0

Summary

This document defines data elements, actions, and link identifiers for a simple class scheduling domain. The material in this document is independent of any Web protocol (HTTP, WebSockets, etc.) and any media type (XML, JSON, HTML, etc.) used to create client-server interactions.

Initial Application

The initial application of this problem domain is to a custom media type design named "Class Scheduling" with the IANA identifier of application/vnd.apiacademy-scheduling+xml. However, there may be other applications of this vocabulary in the future.

Composing a Media-Type Example

Creating valid client requests for this problem domain requires applying the Link Identifer, the Action value, and the Data Elements to a specific media type. For example, below is a response representation that can be used to create a new <<course>> resource using the application/vnd.apiacademy-scheduling+xml media type:

<!-- application/vnd.apiacademy-scheduling+xml example -->
<template name="course" action="add" href="{uri}">
   <data name="courseCapacity" value="15" />
   <data name="courseName" value="Hypermedia 101" />
   <data name="courseDescription" value="An introduction to hypermedia programming." />
</template>

A possible HTML5 representation of the same action might look like this:

<!-- HTML5 example -->
<form name="course" class="add" action="{uri}" method="POST">
  <input type="text" name="courseCapacity" value="15" />
  <input type="text" name="courseName" value="Hypermedia 101" />
  <input type="text" name="courseDescription" value="An introduction to hypermedia programming." />
  <input type="submit" />
</form>

Note	The rules for applying domain details may differ from one media type to the next. The example given here applies to the "Class Scheduling" media type intially defined for this domain.

Actions

Below is a list of the Actions for this problem domain along with the Data Elements associated with each action. Server implementors can Use this as a guide when representing hypermedia transitions within a target media type. Client implementors can use this as a guide when coding clients to recognize, parse, and execute client-server interactions.

add

Add a new resource to the server.

Table 1. Add Actions

LinkID	Data Elements
<<course>>	<<courseCapacity>>, <<courseDescription>>, <<courseName>>
<<schedule>>	<<courseId>>, <<scheduleSlot>>, <<teacherId>>
<<student>>	<<studentName>>, <<studentStanding>>
<<teacher>>	<<teacherName>>

update

Update an existing resource on the server.

Table 2. Update Actions

LinkID	Data Elements
<<course>>	<<courseCapacity>>, <<courseDescription>>, <<courseName>>
<<student>>	<<studentName>>, <<studentStanding>>
<<teacher>>	<<teacherName>>

remove

Remove an existing resource from the server.

Table 3. Remove Actions

LinkID	Data Elements
<<course>>	NONE
<<schedule>>	NONE
<<student>>	NONE
<<teacher>>	NONE

read

Retreive a single resource.

Table 4. Read Actions

LinkID	Data Elements
<<course>>	NONE
<<home>>	NONE
<<schedule>>	NONE
<<student>>	NONE
<<teacher>>	NONE

list

Retrieve a list of resources.

Table 5. List Actions

LinkID	Data Elements
<<course>>	NONE
<<schedule>>	NONE
<<student>>	NONE
<<teacher>>	NONE

filter

Retrieve a filtered list of resources.

Table 6. Filter Actions

LinkID	Data Elements
<<course>>	<<courseName>>
<<student>>	<<studentName>>
<<teacher>>	<<teacherName>>

assign

Assign a student to an existing scheduled course.

Table 7. Assign Actions

LinkID	Data Elements
<<schedule>>	<<studentId>>
<<student>>	<<scheduleId>>

unassign

Remove a student from an existing scheduled course.

Table 8. Unassign Actions

LinkID	Data Elements
<<schedule>>	<<studentId>>
<<student>>	<<scheduleId>>

Link Identifiers

Below is a list of the link and template identifiers for this problem domain.

course

Identifies links that return course information.

home

Identifies the "home" or initial entry page of the service.

schedule

Identifies links that return schedule information.

student

Identifies links that return student information.

teacher

Identifies links that return teacher information.

Data Elements

Below is the list of data elements currently defined for this problem domain.

courseCapacity

Maximum number of students allowed to sign up for the course.

courseDescription

Description of the course.

courseId

System-generated unique ID for the course.

courseName

Name of the course.

scheduleId

System-generated unique ID for the schedule.

scheduleSlot

Time and days of the week for the schduled course.

studentId

System-generated unique ID for the student.

studentName

Name of the registered student.

studentStanding

University standing of the student (freshman, sophomore, junior, senior).

teacherId

System-generated unique ID for the teacher.

teacherName

Name of the teacher

Extensions

This document describes the Class Scheduling domain vocabulary. Domain details from other vocabularies ("foreign domains") can be used in a Class Scheduling document. Any extensions to the this vocabulary MUST not redefine any actions, identifiers, or data elements defined in this document. Clients that do not recognize extensions to this vocabulary SHOULD ignore them.

Warning

It is possible that future forward-compatible modifications to this specification will include new elements, attributes, attribute values, and data types. Extension designers should take care to prevent future modifications from breaking or redefining those extensions.

Acknowledgements

This work was done with the support of Layer 7 Technologies as part of a series of articles for the InfoQ Web site.