2

I'm currently designing a REST API interface and am trying to decide on the best way to structure the calls.

I am providing the ability to create a record in the system. However, the record could be created using two different sets of data, depending on which system calls the data.

I was thinking of providing a url in the format 

/api/create/auto
/api/create/manual

and using the same function (the auto/manual would be a route parameter) to process, with the body containing the appropriate data. However I was wondering if providing url in the format

/api/createauto
/api/createmanual

and use two separate functions to process is a better format to use. The processing involved is fairly simple, I'm just going to take the incoming data and pass it to one of two stored procedures in the database to do the work. If I do it the first way I have to add validation to ensure only the correct values are passed.

Ian Boggs
  • 522
  • 3
  • 16
  • 3
    Not answering your question, but IMO the more [RESTful convention](https://stackoverflow.com/questions/778203/are-there-any-naming-convention-guidelines-for-rest-apis) would be to express the intent to CREATE via the use of `PUT` or `POST` verb, i.e. leave `create` out of the route. – StuartLC May 16 '18 at 16:31
  • 1
    Thanks for the comment. I was just using the ‘create’ as an example and am using POST. I should have chosen a better phrase in my example. – Ian Boggs May 16 '18 at 19:02
  • You can have a route with regex `(auto|manual)` – BrunoLM May 17 '18 at 01:08

2 Answers2

4

REST Api best practices actually states that endpoints should be nouns not verbs. In best practices case the endpoint should be

POST /api/object_name

Then you can either specify auto versus manual through a field in the data body. Otherwise if you really want to specify auto or manual through the URL, you could use a query parameter though I don't think that's actually kosher.

POST /api/object_name?type=auto

Your best bet, would probaby add the type to the json body (assuming you're using json). so something like 

{"type":"auto","data":{data json object}}
George Tuan
  • 56
  • 1
  • Can you provide a link to where it says "REST Api best practices actually states that endpoints should be nouns not verbs", I am curious to learn about this. – AussieJoe May 16 '18 at 16:51
  • 2
    Here is a list to some good rest api resources. http://www.restapitutorial.com/resources.html – George Tuan May 16 '18 at 17:30
  • Thanks. I was considering whether to pass the parameter as part of the Json body as well. My gut was that it should be a single endpoint as, at the end of the day, the result is the same (new record in the system) – Ian Boggs May 16 '18 at 19:09
1

You can have your URLs set up the first way and still point to 2 different functions by using the Route attributes to set the route for each function. 

[Route("create/auto")]
public void AutoCreate(){//do something...}

Link to Microsoft docs on Attribute Routing

M B
  • 2,326
  • 24
  • 33