How to design a REStful API for a media analysis engine

问题

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,

回答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.

来源：https://stackoverflow.com/questions/1645744/how-to-design-a-restful-api-for-a-media-analysis-engine

标签

api

rest

face-recognition