I'm designing a restful API using the ASP.NET MVC Web API stack. I am allowing users to create/update/delete records using the relevant HTTP verb. I accept both XML and JSON content types. I'm currently designing the put (update) method on my first endpoint and ran into a question:
I'm wondering what the best practices are for null/empty fields when updating via an API. Should a null/empty field indicate that the consumer is ignoring the field and does not want it updated or that the field which may or may not have previously had a value, should not currently have a value?
Specifically, when a field has data and an update is sent with null/empty data should this field be a) ignored the b) updated and nulled in the DB
I assume that this is something that comes up a lot, but I haven't been able to find any substantive information (mainly due to the lack of an appropriate search term)
The verb PATCH has been created for partial update.
I would use PUT for full update and PATCH for partial ones. If I remember correctly, support for PATCH is in ASP.NET Web API RC.
Related
I am planning to have these endpoints for our REST APIs.
PUT /tenant/:tenantId/users/save/:username
POST /tenant/:tenantId/users/invite
GET /tenant/:tenantId/users/fetch
GET /tenant/:tenantId/users/fetch/:username
PATCH /tenant/:tenantId/users/activate/:username
POST /tenant/:tenantId/groups/save/
Verbs such as save/fetch/activate are from the consistency point of view. Are these RESTFul according to the REST principles? How should these be changed if at all? Any recommendations?
According to this REST Resource Naming Guide:
RESTful URI should refer to a resource that is a thing (noun) instead of referring to an action (verb) because nouns have properties which verbs do not have – similar to resources have attributes.
And also
URIs should not be used to indicate that a CRUD function is performed. URIs should be used to uniquely identify resources and not any action upon them. HTTP request methods should be used to indicate which CRUD function is performed.
So let's take your first URI as example
PUT /tenant/:tenantId/users/save/:username
Here you are using the verb save. As mentioned before you should not be indicating a CRUD operation in the URI, in this case using a POST would be more appropriate.Here is a guide with the purpose of each HTTP verb. Knowing this, I think that for example a more appropriate URI for that case would be something like
POST /tenants/:tenantId/users/:username
In this cases:
GET /tenant/:tenantId/users/fetch
GET /tenant/:tenantId/users/fetch/:username
you should remove the fetch because you are already telling through the GET verb that data is being fetched. Same goes for the 6th example.
But, this doesn't mean that you can't use verbs in your URIs, in fact there is a specific category called controller which as mentioned in the same guide:
A controller resource models a procedural concept. Controller resources are like executable functions, with parameters and return values; inputs and outputs.
Use “verb” to denote controller archetype.
This controllers resources could go well (I asume) with for example your
GET /tenant/:tenantId/users/activate/:username.
But I would think that the verb activate should go last:
GET /tenant/:tenantId/users/:username/activate
First note: REST doesn't care what spelling conventions you use for your resource identifiers. Once you figure out the right resources, you can choose any identifiers for them that you like (so long as those identifiers are consistent with the production rules defined in RFC 3986).
"Any information that can be named can be a resource" (Fielding, 2000), but its probably most useful to think about resources as abstractions of documents. We use HTTP as an application protocol whose application domain is the transfer of documents over a network.
GET
This is the method we use to retrieve a document
PATCH
PUT
POST
These methods all indicate requests to edit a document (specifically, to edit the request target).
PUT and PATCH are each ask the server to make its copy of a document look like the client's local copy. Imagine loading a web page into an editor, making changes, and then "saving" those changes back to the server.
POST is less specific; "here's a document that we created by filling in a web form, edit yourself appropriately". It is okay to use POST: after all, the web was catastrophically successful and we're still using POST in our form submissions.
The useful work is a side effect of these edits.
Are these RESTFul according to the REST principles?
Do they work like a web site? If they work like a web site: meaning you follow links, and send information to the server by submitting forms, or editing the webpages and submitting your changes to the server, then it is REST.
A trick though: it is normal in REST that a single method + request uri might have different useful side effects. We can have several different HTML forms that all share the same Form.action. Uploading changes to an order document might have very different effects if the edits are to the shipping address vs to the billing information or the order items.
Normal doesn't mean obligatory - if you prefer a resource model where each form request goes to a specific resource, that can be OK too. You get simpler semantics, but you support more resources, which can make caching trickier.
How to refresh the interface after you add a strip of data to the backend database in Vue.js?
I mean, if I add a item data to the database. there are two case for refresh the interface.
refresh the list api to get the page data.
append the added item data to local list.
what is the best way to do this?
I think both the solutions are valid it depends on what kind of write operation we are planning to do. Given that you do all the validations on the front-end which leaves lesser chance for errors on the backend. I do the following based on the use case.
Add/Update the item locally and then based on the response from the server I remove it again in case of an error. This is an optimistic technique used by a lot of websites and worls really well for CRUD kind of operations.
Let's say that your new operating is going to creaate a new user in a 3rd party api. So doing an optimistic thing might not be the best. So what I do is make the request, show a toast/alert that the request is happening, and then use sockets or long polling to get the changes. When the request is finally done show the data. In the meanwhile you can insert a dummy item showing loading.
I am creating Cars store in Asp.Net for my school.
I built an Api Method:
[HttpGet("api/brands/{brandName}/models")]
public IActionResult Get(string brandName)
{
{
var model = _context.getBrandByName(brandName);
return Ok(model.Models.ToList());
}
}
An it works when I am checking it with Postman.
Now I would like User to choose brandName from selection list in the website and show him avaliable models.
In other words I dont know how to use this Api to get Data displayed.
Any help will be strongly appreciated
RESTful Web services are one way of providing interoperability between computer systems on the Internet. REST-compliant Web services allow requesting systems to access and manipulate textual representations of Web resources using a uniform and predefined set of stateless operations.
from Wikipedia.
This means, the REST API's only concern is to provide the data to work in a uniform and predefined set of operations, where those operations take the HTTP Verb that was used in consideration.
in your example, your GET route, should only be api/brands/{brandName}
the default in rest api, http verbs say:
GET - getting one element or a list
POST - creating
PUT - updating
DELETE - removing
in your application, the best approach would be something like:
GET /api/brands will get ALL existing brands
GET /api/brands/<brand_name> will get just one brand
POST /api/brands will create a new brand
PUT /api/brands will edit an existing brand
DELETE /api/brands will delete an existing brand
from your question:
Now I would like User to choose brandName from selection list on the website
the website would then request a GET to the route /api/brands to get the list of all of the brands.
This is the REST API part, it concerns ONLY in providing the right data to the system that request it.
if you want to create a website in order to CONSUME this data, you can easily create a new web project in your solution and request the data that the API provides, making the Website completely "blind" from where the data comes from, as it only asks for the data itself.
Making the whole system much easier for updated and maintainability.
In other words I dont know how to use this Api to get Data displayed.
The main purpose of REST API is to expose data not to display it by using any kind of UI framework.
If you think you need to manage the full stack of your application end-to-end. I mean from User interface to your database then you must think at implementing the V of the MVC pattern bu return a view and not just a data. ASP.Net Core can help you with that. Follow this tutorial, it explains a lot about this pattern in ASP.Net Core MVC.
I have tried out the RESTful API concept and found out that its a great mindset for building resources APIs. For example, adding comment to post would be
POST /posts/{id}/comments
However, there are some cases, correct me if I am wrong, that the expected APIs can not really be model as a simple CRUD
For example, adding product to the system requires adding picture, adding multiple tags specify its category?
How do I do this the restful way?
1.) Do I force the API user to follow after multiple API calls?
POST /pictures -- add picture
GET /categories -- get selected category
POST /tags -- add tags
POST /products -- input picture, category, tags ids as JSON fields
2.) Do I use nested object which automatically do find all subresources?
POST /products -- input nested JSON array with picture/category/tags object field
In this case, all subresources will be existing resources instead of some (picture, tags) that should be posted.
Also, what would happen if adding picture succeed internally but adding tags failed?
3.) Do I just do a casual API? How does this fit with REST? Doesn't this break the RESTful idea?
POST /add_products
Is there any guide to deal with complex API for RESTful APIs?
Thank you.
In my opinion, one of the biggest misconception people have about REST is that internal models (tables in db or document in mongo) and REST resources must be same. REST resources can be a real model or it can be an abstract entity as well which might not exist in db.
So in this case, your url with POST i.e. POST /products request is perfectly alright as far as REST is concerned. And advice from my personal experience - One doesn't needs to be too dogmatic about url as long as basic principles of REST are conserved such as
Use right HTTP verbs
Use right status codes
Cacheable architecture
Unique indentification of resource by url
Hypermedia (if you can go that far)
We are creating a RESTful API (PHP on apache server) which will communicate with an Android application. Im new for this so excuse me if my question is dumb.
I want to ask for data from the api so I need to use GET method in the request taking into account the semantics. I have to send some additional data to specify what data am I requesting. In GET requests, I cannot send form data fields so how should I attach the data?
Using POST (but this is not semantic)
request header: POST http://example.com/api/v1/serials
request data: date_from=2013.01.01&date_to=2014.01.01&userid=112&is_in=0&starts_with=afx00
using GET and adding url params (I don't know if is this a good practice in a REST API)
request header: GET http://example.com/api/v1/serials?date_from=2013.01.01&date_to=2014.01.01&userid=112&is_in=0&starts_with=afx00
or making well formed URIs with no url params in GET (not sure about this as well.)
request header: GET http://example.com/api/v1/serials/date_from/2013.01.01/date_to/2014.01.01/userid/112/is_in/0/starts_with/afx00
Which one fits the best in the RESTful API architecture? Which should I use and why? Or maybe are there any other options for what I want?
Without question using URL parameters is best. It allows consumers to query for serials using their choice of filters. Your API should support returning results based on UserId alone, or a date range, or both. Or other combinations of inputs that make sense.
Embedding the key/value pairs of the filter in the resource path is an anti-pattern. It's difficult to understand what each path element means, and you would need to contort your routing engine to accommodate additional filter criteria. It also provides no flexibility in terms of choosing what filter criteria to use - you would in fact need to construct multiple resources paths for each combination of filters. And there is the management of ordering each pair (with URL params, ordering doesn't matter). Probably more reasons to avoid this, but those are the first that spring to mind.
Bot GET methods can be used. It is your choise. But I'll prefer using url params. It is easier.