How to design a REStful API for a media analysis engine

Question

I am new to Restful concept and have to design a simple API for a media analysis service I need to set up, to perform various tasks, e.g. face analysis, region detection, etc. on uploaded images and video.

Outline of my initial design is as follows:

• Client POSTs a configuration XML file to http://manalysis.com/facerecognition. This creates a profile that can be used for multiple analysis sessions. Response XML includes a ProfileID to refer to this profile. Clients can skip this step to use the default config parameters
• Client POSTs video data to be analyzed to http://manalysis.com/facerecognition (with ProfileID as a parameter, if it's set up). This creates an analysis session. Return XML has the SessionID.
• Client can send a GET to http://manalysis.com/facerecognition/SessionID to receive the status of the session.

Am I on the right track? Specifically, I have the following questions:

• Should I include facerecognition in the URL? Roy Fielding says that "a REST API must not define fixed resource names or hierarchies" Is this an instance of that mistake?
• The analysis results can either be returned to the client in one large XML file or when each event is detected. How should I tell the analysis engine where to return the results?
• Should I explicitly delete a profile when analysis is done, through a DELETE call?

Thanks,

C

Answer 1

You can fix the entry point url,

GET /facerecognition

<FaceRecognitionService>
  <Profiles href="/facerecognition/profiles"/>
  <AnalysisRequests href="/facerecognition/analysisrequests"/>
</FaceRecognitionService>

Create a new profile by posting the XML profile to the URL in the href attribute of the Profiles element

POST /facerecognition/profiles
201 - Created
Location: /facerecognition/profile/33

Initiate the analysis by creating a new Analysis Request. I would avoid using the term session as it is too generic and has lots of negative associations in the REST world.

POST /facerecognition/analysisrequests?profileId=33
201 - Created
Location: /facerecognition/analysisrequest/2103

Check the status of the process

GET /facerecognition/analysisrequest/2103

<AnalysisRequest>
   <Status>Processing</Status>
   <Cancel Method="DELETE" href="/facerecognition/analysisrequest/2103" />
</AnalysisRequest>

when the processing has finished, the same GET could return

<AnalysisRequest>
   <Status>Completed</Status>
   <Results href="/facerecognition/analysisrequest/2103/results" />
</AnalysisRequest>

The specific URLs that I have chosen are relatively arbitrary, you can use whatever is the clearest to you.