Overview
Directory interface
Notebook interface
Background information

Overview

DiNo has two interfaces that each team MUST implement EXACTLY as defined. If you don't implement these interfaces accurately, your implementation will not integrated with other teams' implementations. Each interface is described here. They are the directory interface and the notebook interface. 

Back to top

Directory interface

The directory interface has methods for managing the directory of all notebooks in the system, including titles, ids and primary servers.

The directory interface is an EJB interface. The DiNo directory client jar, including source and class files for the interface, is available. The javadoc is available online. The reference implementation of the directory interface is here.

package dino.api;

import java.util.List;
import javax.ejb.Remote;

@Remote
public interface Directory {
    List<Notebook> getAllNotebooks();
    Notebook getNotebook(String id);
    String createNotebook(String title, String primaryUrl)
        throws NotebookAlreadyExistsException, BadAddressException;
    void deleteNotebook(String id)
        throws NotebookNotFoundException;
}

Back to top

Notebook interface

• URIs
• Methods
• Headers
• Content
• GET requests
• POST requests
• PUT requests
• DELETE requests
• Response codes

URIs

Resource	Used when
/all	Getting a list of all notebooks in the system
/notebook	Creating a notebook Getting a list of existing notebooks
/notebook/notebookId	Deleting a notebook Getting a notebook's complete content (header and notes)
/secondary/notebookId	Creating a secondary copy of a notebook Deleting a secondary copy of a notebook
/notes/notebookId	Adding a note to a notebook Getting a notebook's complete content
/notes/notebookId/noteId	Replacing a note Deleting a note Getting the contents of a note
/config/self	Getting the host:port this notebook service instance uses when registering with the directory service as the primary server for a notebook
/config/self/hostport	Setting the host:port this notebook service uses when registering with the directory service as the primary server for a notebook
/config/jndi	Getting the host:port used to look up the directory service
/config/jndi/hostport	Setting the host:port used to look up the directory service

Data types in URIs:

• notebookIds and noteIds must be strings of length one or more, consisting of letters, numbers and hyphens.

Back to top of notebook interface

Methods

GET

All lookups in DiNo are done with GET requests. The URIs used in GET requests are side-effect free, bookmark-able and cacheable. The only reason for a change in the results of a GET request is an update to the underlying content.

POST

DiNo uses POST requests for creating things.

PUT

DiNo uses PUT requests for updating things.

DELETE

It should come as no surprise that DiNo uses DELETE requests for deleting things.

Back to top of notebook interface

Headers

All notebook service requests and response that have content should include the header

Content-Type: text/xml;charset=utf-8

And of course, the content should actually be UTF-8 encoded. I plan to use only ASCII data for testing, so you will not have to do anything to ensure that your content is UTF-8 encoded. If you have the time and interest, clearing the path for non-ASCII data through your implementation would be highly educational (but doing that is NOT a requirement of this project)

Back to top of notebook interface

Content

This section lists each type of request, and describes its expected request content, if any, response content, if any, and possible error conditions.

General content requirements:

• Request and response content must conform to the DiNo XML schema.
• In case of error, an appropriate response code should be returned, and an appropriate error message should be returned as the response message. The possible response codes for each type of request are listed below.

Back to top of notebook interface

GET /all

The response is a list of all notebooks in the system.

Request content	Response content	Additional information
none	notebook-list   notebook*     id     title	It is NOT an error if DiNo has no notebooks. In that case, the notebooklist element should be empty.

Possible errors:

• none

GET /notebook

The response is a list of notebooks known to the server.

Request content	Response content	Additional information
none	notebook-list   notebook*     id     title	It is NOT an error if the service knows of no notebooks. In that case, the notebooklist element should be empty.

Possible errors:

• none

GET /notebook/notebookId

The response consists of the requested notebook's header and notes, if any.

Request content	Response content	Additional information
none	notebook   id   title   note*     id     content	In this case, it IS an error if the service knows of no notebook with the requested id.

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook with the given id

GET /notes/notebookId

Same as GET /notebook/notebookId.

GET /notes/notebookId/noteId

Retrieves the data for a given note. The response is the requested note.

Request content	Response content	Additional information
none	note   id   content	none

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook or note with the given id

GET /config/self

Returns the host:port this notebook service instance uses when registering with the directory service as the primary server for a notebook

Request content	Response content	Additional information
none	host:port	Use a reasonable content type for the response. Typically, this means text/plain or text/html, but it could be text/xml, if you decide to define an XML format for configuration data

Possible errors:

• none

GET /config/jndi

Returns the host:port or host used to look up the directory service. If only a host is returned, the caller can assume the GlassFish default JNDI port (3700)

Request content	Response content	Additional information
none	host:port   or host	Use a reasonable content type for the response. Typically, this means text/plain or text/html, but it could be text/xml, if you decide to define an XML format for configuration data

Possible errors:

• none

POST /notebook

Creates a new notebook. The request content consists of the new notebook's header, with only a title. For a successful request, the response content is the notebook's header, updated to include the newly-assigned id and the URL of the primary server.

Request content	Response content	Additional information
notebook   title	notebook   id   title	The title is required, and it must not already exist in the system

Possible errors:

• 400 - Bad request
• 409 - Conflict; occurs when a notebook with the given title already exists.

POST /secondary/notebookId

Creates a secondary copy of a notebook in the server that receives the request. The secondary server is responsible for notifying the primary that the secondary copy has been created.

Request content	Response content	Additional information
none	none	The secondary server is responsible for informing the primary server about its existence. How this works is up to each team to decide. The secondary server can query the directory service to find the primary, and it can get the notebook's data from the primary.

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook with the given id
• 409 - Conflict; occurs if the primary server for the notebook receives this request, or if the receiver is already a secondary server for the notebook

POST /notes/notebookId

Creates a note in the given notebook. The request content must be a <note> element containing only a <content> element. The response is the new note, including the noteId assigned by the primary server.

If a secondary server for the notebook receives this request, it should re-submit it to the notebook's primary server, and return the response code and content received.

When a note is created, the notebook's primary server is responsible for informing any secondary copies about the new note. Your team is responsible for designing a way to make this happen.

Request content	Response content	Additional information
note   content	note   id   content	none

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook with the given id

Back to top of notebook interface

---

PUT /notes/notebookId/noteId

Replaces an existing note's content. The request content must be a <note> element containing only a <content> element.

If a secondary server for the notebook receives this request, it should re-submit it to the notebook's primary server, and return the response code received.

When a note is updated, the notebook's primary server is responsible for informing any secondary copies about the updated note. Your team is responsible for designing a way to make this happen.

Request content	Response content	Additional information
note   content	none	The note's content is replaced with the value from the request

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook or note with the given id

PUT /config/self/hostport

Sets the host:port this notebook service instance uses when registering with the directory service as the primary server for a notebook

Request content	Response content	Additional information
none	none	you may (or may not) need to URL-encode the colon as "%3A", for example somehost%3A6789 is the URL-encoded form of somehost:6789

Possible errors:

• 400 - Bad request; occurs if hostport cannot be parsed as a hostname:portnumber

PUT /config/jndi/hostport

Sets the host:port or host this notebook service instance should use to look up the directory service. If only a host is provided, DiNo can assume the GlassFish default JNDI port (3700)

Request content	Response content	Additional information
none	none	you may (or may not) need to URL-encode the colon as "%3A", for example somehost%3A6789 is the URL-encoded form of somehost:6789

Possible errors:

• 400 - Bad request; occurs if hostport cannot be parsed as a hostname or hostname:portnumber

Back to top of notebook interface

---

DELETE  /notebook/notebookId

Deletes a notebook. DELETE commands have no content. There is no response content.

If a server with a secondary copy of the notebook receives this request, it should re-submit the request to the notebook's primary server.

When a notebook is deleted, the notebook's primary server is responsible for informing any secondary copies about the deletion. Your team is responsible for designing a way to make this happen.

Request content	Response content	Additional information
none	none	none

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook with the given id

DELETE  /secondary/notebookId

Deletes a secondary copy of a notebook. When a notebook's secondary server receives this request, it should delete its copy of the notebook, and inform the primary server. Your team is responsible for deciding how this should work.

Request content	Response content	Additional information
none	none	none

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook with the given id
• 409 - Conflict; occurs if the notebook's primary server receives this request

DELETE  /notes/notebookId/noteId

Deletes a note.

If a secondary server receives this request, it should re-submit the request to the primary server.

When a note is deleted, the notebook's primary server is responsible for informing any secondary copies about the deletion. Your team is responsible for designing a way to make this happen.

Request content	Response content	Additional information
none	none	none

Possible errors:

• 400 - Bad request
• 404 - Not found; occurs if there is no notebook or note with the given id

Back to top of notebook interface

---

Response codes

Successful DiNo requests should return 200 - OK, except for successful POST requests, which should return 201 - Created.

Whenever the request URI or content contains a syntactic error that prevents processing, for example if the URI does not conform to the formats described in the URI section, the server should return a Bad Request response code and an appropriate response message.

The complete list of possible error codes is as follows:

• 400 - Bad request
• 404 - Not found
• 409 - Conflict

See the content section for details on when these error codes should be returned.

Back to top

---

Background information

• Introduction to XML schema
• How to define a RESTful interface

Back to top