I have created REST apis to manage a resource (with endpoint say /user/resource ). I can query the resource making a GET call and create the resource using the POST call. I use the api to manage resources from UI by making ajax calls to the REST api endpoint.
Now there is a requirement to send an email upon creating resource, and if the resource is already existing then sending a mail with the resource details in the mail (without modifying the resource) . I am confused if sending mail should be part of the the original REST api used for creating the resource or sending the mail should be handled separately . If "sending the mail" isn't part of the original REST api then it would involve some more handling on my UI for making another call to send a mail. Also if i expose "sending the mail" logic by means of another REST api then how should the endpoint be structured , will it be something like /user/resource/email since the mail sending is only related to the resource or should it be /user/email
Your question is not very clear. However, you can try to send mail in same api where you are performing business operation.
For example:
public Object createResource() {
//Perform your business operation here
//check if your resource is already exists or not. Depending on the result call
Object sendEail(..,..,..);
}
private Object sendEail(String address,String subject,String body) {
//Write code for sending mail here
}
I hope you understand my point.
Related
I have created an envelope, added recipients and documents to the envelope through REST API call in apex code. Now I want to view my envelope in docusign user interface before ot it sent to the signers. Can I connect to the docusign from REST API call in apex and view the envelope?
There are different type of views you can use, based on the Envelope status, details are available at https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeViews/ You might be interested in seeing https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeViews/createCorrect/ or https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeViews/createEdit/ or if sender wants to see it then https://docs.docusign.com/esign/restapi/Envelopes/EnvelopeViews/createSender/
You can use the EnvelopeViews: createSender API (also called Embedded Sending) to open the "tag and send" view of the envelope and let your users send it through the DocuSign Console. This also allows them to make changes to envelope before sending, given that they have the correct permissions.
This is what the API request typically looks like:
POST /v2/accounts/{accountId}/envelopes/{envelopeId}/views/sender
{
"returnUrl": "https://your.app.com/callback"
}
Once the user is done sending the envelope they will be redirected to the URL that's provided in the returnUrl parameter.
I'm designing a REST api that allow client side to POST (create) a resource.
Let's call my resource is Subscription and my REST api accepts a Dto called Subscription
The POST request needs to be sent together with a captcha token that will be verified on server side.
My question is where would be the best place to put the captcha token, there're some options that I'm thinking about:
Directly inside Subscription
As a parameter in URL, e.g: /subscriptions?captcha_token=abcd1234
As a HTTP header
Create a new Dto that wraps Subscription and carry field captchaToken
Any other suggestion are welcome.
Thank you.
For anything authentication or authorization related I typically rely on headers or querystring parameters.
Generally I don't like to commingle payload with auth-related material, nor do I like to encapsulate it.
Having it in an HTTP header or as a querystring parameter gives you a good amount of isolation there. Also since it's independent of the request body you can implement broader auth controls for every API call without being dependent on the presence of a request body (important for GET requests which shouldn't carry a request body anyway).
Using a HTTP Header is only an option if your clients can modify / send HTTP Header information. This approach does not work for Standard Browsers.
You are not filtering a resource, so a query parameter from the REST Point of view does not make sense, and you don't want to send the captcha answer as query parameter.
Usually the one submits the captcha information (id, answer) together with the form data (payload). You also usually display captchas together with the form.
So at the end the only useful option is to send the captcha information as part of the payload / form data.
If you should put the data into your Subscription DTO or not depends on your design / preferences.
I'd suggest to use something like a Subscription(Data) and SubscriptionRequest where the SubscriptionRequest contains the SubscriptionDataand the Captha Information (capcha id and answer)
I'm trying to build a simple Email Verification API. Below you can find the expected client requests in order:
The client gets an email address as an input. (e.g. mail#example.com)
The client sends a request: GET /emails/?email=mail#example.com
If mail#example.com has not been created before, meaning the previous request returns an empty list as a response, it sends a request: POST /emails/ where email#example.com is in the request body parameters.
The client sends a request: POST /email-verifications/ with email_id in the request body and creates a new email verification object. Upon successful creation, the client receives a token in the response body and 6-digit verification code is sent to the corresponding email address.
Now the client gets verification code as an input from the user.
The client sends a request: PATCH /email-verifications/id/ with token and code in the request body.
I'm not exactly sure about the last step since the corresponding update operation receives two inputs as token and code that won't be updated in the instance. Rather, they will be compared with the existing instance and upon success another field is_verified will be updated.
Is this a right way to implement such operation? Or are there any better practices that I can follow?
PATCH is often not the perfect fit for things, and I think that you probably also shouldn't be using it here.
We've ran into a similar issue as you did and wondered how to design it. In our example it wasn't a token and code but it was an API for changing a users password.
Also in our case, a client would send a new password to a server but the server would never return the password.
The most appropriate solution for us ended up being a special password resource, with a url like:
/users/x/password
A GET request on this url would always yield a 403, and only a PUT request will be supported here. I kinda have the feeling that your design problem should be solved the same way.
My company is currently writting a REST API where they allow querying for Active Directory specific information via a POST requests.
In the request body the following information gets sent to the API:
Filter (LDAP)
Properties to return (e.g userAccountControl, sAMAccountName)
From a personal point of view I would have definitely realised it via simple GET methods.
Is the POST method approach the recommended way to so? Are there any particular reasons to implement it with POST?
I can see slight advantages of using a POST request. It is certainly more secure for sending any sensitive data, because the body of the request is not cached by the user's browser and other network devices on the way. Also a POST request allows you to send an unlimited amount of data, but that is probably not relevant for this use case.
When a user register to my web application I send an email to verify his inbox.
In the email there are a link to a resource like this:
GET /verify/{token}
Since the resource is being updated behind the scenes, doesn't it break the RESTful approach?
How can I do it in a RESTful manner?
What you are talking about is not REST. REST is for machine to machine communication and not for human to machine communication. You can develop a 1st party REST client, which sends the activation to the REST service.
You can use your verification URI in the browser to access the REST client:
# user follows a hyperlink in the browser manually
GET example.com/client/v1/verify/{token}
# asking the client to verify the token
and after that the REST client will get the hyperlink for verification from the REST service and send the POST to the service in the background.
# the REST client follows the hyperlinks given by the service automatically
# the REST client can run either on the HTTP client or server side
GET example.com/api/v1
# getting the starting page of the REST service
# getting the hyperlink for verification
POST example.com/api/v1/verification {token}
# following the verification hyperlink
If you have a server side 1st party REST client, then the HTTP requests to the REST service will run completely on the server and you won't see anything about it in the browser. If you have a client side REST client, then you can send the POST in the browser with AJAX CORS or you can try to POST directly with a HTML form (not recommended). Anyways the activation should be a POST or a PUT.
It depends on what are you trying to do.
Does it fire an email after validating the user for example? If so, it is not an idempotent method and you should use POST.
Example:
POST /users/{id}/verify/{token}
If the method doesn't have any consequence besides the update, I think you should use PUT.
Aren't you overthinking REST? With e-mail verification you want the user to be able to simply click the link from whatever mail user agent he is using, so you'll end up with a simple GET on the server (presented as a hyperlink to the user) with the token either in the path or as part of the query string:
GET http://example.com/verify-email/TOKEN
GET http://example.com/verify-email?token=TOKEN
Either is fine for this use case. It is not really a resource you are getting or creating; just a trigger for some process on the backend.
Why do you think this would run afoul of good design?