I’m defining a new schema for a restful api which can get and add notifications. An existing endpoint notifications is already used for something else unfortunately, so I have two ideas on what to do instead.
/NotificationAPI/1.0.0/notification_endpoints
or
/NotificationAPI/1.0.0/notification_configurations
Which one do you find makes more sense?
Related
Let's say we have the resource: api/v1/cars/{id}
How one can actually know whether he or she can have access to this particular resource? api/v1/auth/cars/{id}?
First it would have been better to have something else than just leveraging resources just in order to browse in an Angular app (I fully acknowledge that point) like for example using Identity framework with ASP.NET.
Anyway back to the point, I listed a few solutions
GET api/v1/cars/{id} and leverage the error code
HEAD api/v1/cars/{id} and still leverage the error code without transferring a whole body
OPTIONS api/v1/cars/{id} (a bit twisted but does not return an error) to know whether is actually gettable
Another resource, e.g.
GET api/v1/cars/{id}/authorized
GET api/v1/auth/me/cars/{entityId}
I ended up using the first solution and use resolve guard in my Angular app, the most "standard" way of achieving it, even though I found that personally ugly.
I have a couple of microservices and would like to be able to see every endpoint that a specific API call goes through. In essence, given a requestID, I should be able to generate a sequence diagram of its journey.
Research suggests that I need to attach a UUID to a every request, then I can log the request to ELK wherever I am interested. Seems logical.
My concerns:
How do you guarantee that some intermediate service or function does not strip or change this requestID?
Is it a good idea to generate the ID in the client or the API gateway?
Where would you keep this requestID: header? body? url parameter?
Rather than hypothetical recommendations (which I have already considered), I would appreciate real-world experience from someone who has done this. Thanks.
We have a series of REST services that pull resources by identifier but we've been recently tasked with passing disclosure parameters to save with audit.
What use to be...
GET entity/{id}
now turns into something like...
GET entity/{id}?requestName=&requestingOrganization=&reasonForUse=&verificationMethod=&otherAuditDisclosureProperties....
The state of entity does not change and is still idempotent however we must audit the additional information with each call in order to provide it.
First thought was to construct a body instead but that did not seem proper for a GET. This is the second approach using query parameters which have no intention of querying/filtering. These additional parameters are truly context information captured at the point of request. These are the equivalent of SAML attributes within a SOAP call that live outside of the SOAP body (which makes me think as possible header attributes).
Also note, that this information is relayed so the authentication token provided is for the service user calling in and not the actual identity of the context. The identity of the original caller is implicitly trusted in the trust framework surrounding.
How would you define this verb/path?
Maybe a custom header: vnd.mycompany.myheader; where you put all the params you need in some parseable format: name1=value1; name2=value2. You take the waste out of the query string.
The off-topic response
I cannot imagine an scenario where you are asking the user of an API for such subjective information, that requires a lot of effort to provide (as it changes per request) and provides no value to the client. It is only for your internal use. The most probable result is clients hard coding those values and repeating them over in all requests.
If the client is internal you may be looking for ways to correlate requests that span multiple services, like Sleuth, which will let you understand why clients are using your API.
If the client is external, think of making surveys and personal interviews with developers. I'd also suggest that you first nurture your API community to reach those people and understand how and why they use your API.
I agree with Daniel Cerecedo. The proper way is to add the information as part of your Request Header.
A general information can be found at: https://www.w3.org/Protocols/HTTP/HTRQ_Headers.html
The implementation will depends on your programming language.
we are creating some REST API documentation. There are locations which blow to company. So we have created an action at the following path:
/company/{companyId}/locations
For me it is logical and i think it's in accordance with REST to GET at:
/company/{companyId}/locations/{locationID}
It should return an instance of the location, because I have created it there.
But my backend programmer insisted that it's not convenient because he must get the company object on every call. He says that I should do GET, PUT and DELETE actions at the following:
/locations/{locationID}
How to convince him that it's a good idea to have URL cohesion?
I think your programmer is right, you should add hyperlinks to the responses rather than building nested URI structures which are meaningless to the clients. Read more about HATEOAS and uniform interface constraint.
This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
How to version REST URIs
I'm currently writing a REST service and I would like to get some ideas on how my clients can specify the service version when making a request.
For example when I upgrade my REST server to version 2 I don't want calls to break for all clients that have implemented version 1 of my service.
I've seen others add the version in the url or specify the version in the header somewhere.
There may not be a "best" way to implement this but I would appreciate some thoughts on the subject( pro's and con's of each etc...)
Thanks
We do it via separate routes:
http://my.service.com/v1/user/1
http://my.service.com/v2/user/1
In the case of no change between versions, we just map the route to the controller that services the v1 version of the resource.
Yes, this does create multiple URL's for the same resource, and the wonky hardcore REST evanginlists will start crying, but this way makes it easy to manage for you and your users. I find users can't even use request headers to set things like content types nevermind an X-Path or something like that to handle versioning....
If you really want to avoid the duplicate resource issue, you couldpass in a get paramter like version:
http://my.service.com/user/1?version=1
If no version, default to whatever. This is actually fully REST dogmatic, but I think it puts a lot onto your API users.
You could do some kind of user lookup table to route between version if you have a way to map user or api key to version, but this is pretty crazy overhead.
I would recommend versioning via the Accept/Content-Type header. The URIs shouldn't change across versions unless there is a large structural change to the resources themselves. Here is a great explanation: Best practices for API versioning?