Home/ Questions/Q 431497
In Process

The Archive Base Latest Questions

Editorial Team
  • 0
Asked: 2026-05-12T19:58:50+00:00

I am new to Restful concept and have to design a simple API for

  • 0

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

Share

Leave an answer

You must login to add an answer.

Need An Account,

1 Answer

  1. Editorial Team

    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.

    • 0