I cannot find documentation on the list of constants for Request Transaction Types. In the examples I've come across, in a disorganized way, the two common types of "authOnly Transaction" and "authCaptureTransaction".
Where does Authorize.Net document this on their website with a full list and the meaning of each constant?
Are there only two?
If you look into the the API Schema of Authorize.Net these are the list of transactionType accepted by the API :
authOnlyTransaction
authCaptureTransaction
captureOnlyTransaction
refundTransaction
priorAuthCaptureTransaction
voidTransaction
getDetailsTransaction
authOnlyContinueTransaction
authCaptureContinueTransaction
All of the constants and other related documentation can be found in the AIM documentation.
Related
Let's say I have an API that creates me a resource say /create/my-resource/<resource-id>. I want the consumers of the api to know that the response will always have an id field matching the one passed in the url, namely: <resource-id>.
I know I can use api examples to demonstrate this for a given id, say 2. But is there a way of describing that generically, purely using open-api? The idea is to use the said behaviour when mocking.
OpenAPI does not have syntax for that. You can only document such behavior in the description or using custom x- extensions.
Feel free to propose an enhancement for OpenAPI syntax here:
https://github.com/OAI/OpenAPI-Specification/issues
I read following books and links before I post this question and since this question is about best practices, this question might be closed. However i am expecting some expert views.
https://www.restapitutorial.com/resources.html
REST-API-Design-Rulebook book from oreily
other blogpost and stackoverflow question.
For example to get information about employee with id we are using uri as below
http://myapp-name.myorganization.com/employees/employeeid/123456
But all above resources tell me to do this way
http://myapp-name.myorganization.com/employees/123456
Similarly if i want go get information about employee with id 12345, my uri is as below
http://myapp-name.myorganization.com/countries/country/US/employeeid/12345
as opposed to
http://myapp-name.myorganization.com/countries/US/12345
Does that mean my uri are not standard?
They are just guidelines. You can't cover all kinds of possibilities of your business and necessities on a Rest documentation.
Talking about your examples, the
http://myapp-name.myorganization.com/employees/employeeid/123456
And
http://myapp-name.myorganization.com/employees/123456
Are both correct. But could be better (shorter).
Usually I prefer the second one and use the first one for the alternatives. Per example, if I would like to find an employee by id (the "default" method to find employees) or his unique internal company code, I prefer to use respectively:
/employees/123456 # by id
/employees/code/A899123A # by code
Similarly if i want go get information about employee with id 12345,
my uri is as below
http://myapp-name.myorganization.com/countries/country/US/employeeid/12345
This URL means to me that you trying to find an employee with id 12345 on the US country. But could be shorter too if the US term is the default method to find countries on your API:
/countries/US/employees/12345
as opposed to http://myapp-name.myorganization.com/countries/US/12345
This one seems confuse. Are you trying to find what with id 12345? It's hard to answer only looking for the URL. So, the /countries/US/employees/12345 is more consistent.
If the idea is find the employee on some country with some code, the URL can follow the same pattern: /countries/US/employees/code/A899123A
Does that my uri are not standard?
No, your URI are fine. REST doesn't care what spellings you use for your identifiers, so long as they are consistent with RFC 3986. There's also RFC 7320, which describes "Best Practices" -- but you will probably find that those best practices still leave you with a lot of freedom.
Think "variable names" - various communities will have their own conventions for how variable names should be spelled, but there isn't any standard.
The same holds for identifiers in REST -- they are opaque strings that neither the API consumer nor the client actually need to parse. (Example: when's the last time you actually looked at the URI used when you submit a search to Google?)
Some routing frameworks will be easier to use if you adhere to a particular convention, but that's purely an implementation detail on the server, the client doesn't care.
my REST API format:
http://example.com/api/v1.0/products - get all products
http://example.com/api/v1.0/products/3 - get product with id=3
Also, the products can be orginized into a product groups.
What is a proper way to get all product groups according to REST best practices:
http://example.com/api/v1.0/products/groups
or
http://example.com/api/v1.0/productgroups
...
another option ?
I can't agree with Rishabh Soni because http://example.com/api/v1.0/products/groups may lead to ambiguity.
I would put my money on http://example.com/api/v1.0/productgroups or even better http://example.com/api/v1.0/product_groups (better readability).
I've had similar discussion here: Updating RESTful resources against aggregate roots only
Question: About the thing of /products/features or /product-features,
is there any consensus on this? Do you know any good source to ensure
that it's not just a matter of taste?
Answer: I think this is misleading. I would expect to get all features
in all products rather than get all possible features. But, to be
honest, it’s hard to find any source talking directly about this
problem, but there is a bunch of articles where people don’t try to
create nested resources like /products/features, but do this
separately.
So, we can't be sure http://example.com/api/v1.0/products/groups will return all possible groups or just all groups that are connected with all existing products (what about a group that has not been connected with the product yet?).
To avoid this ambiguity, you can add some annotation in documentation. But you can just prepare http://example.com/api/v1.0/product_groups and all is clear.
If you are developing Rest API for your clients than you should not rely on id's. Instead build a meaningful abbreviation and map them to actual id on server side.
If that is not possible, instead of using
http://example.com/api/v1.0/products/3 you can use http://example.com/api/v1.0/products?product_id=3 and then you can provide "product_id" description in the documentation. basically telling the client ways to use product_id.
In short a url must be meaningful and follow a pattern.The variable part must be send by in the url query(part after ? or POST payload)
With this, method to querying the server is also important. If client is trying to get something to the server he should use "GET" http request, similar POST http request if it is uploading new info and "PUT" request if it is updating or creating a new resource.
So by this analogy http://example.com/api/v1.0/products/groups is more appropriate as it is following a pattern(groups in product) while productgroups is more like a keyword with no pattern.
A directory like pattern is more easier to understand. Like in file systems(C:\Program Files\WinRAR), every part gets us to more generalized target.
You can also customize this for specific group- http://example.com/api/v1.0/products/groups?id=3
My questions concern the Transaction data object in Intuit's Customer Account Data API.
I am not sure how to use the following fields (or even really what they mean):
correctAction: The documentation does mention that "replace" and "delete" are possible values, which leads me to think that the word "correct" is being used to mean "fix", not as in the opposite of "incorrect".
correctInstitutionTransactionId: The documentation does not provide any details on this field. My best guess is that this id is used in conjunction with the "correctAction" field. I do not know how.
How do I use these fields?
Given that we provide a restful api that serves book entities listening at
/books
And a client can get a book at the usual
GET /books/{id}
Suppose that we want to begin offering discounts on books to only our most vigilant buyers. These buyers would be given a discount code, and that code will reduce the price of the book.
Thus, a generic response may be
GET /books/4
{"id":4, "price":"24.95"}
Where a response to a query with a discount code may be
GET /books/4
{"id":4, "price":"24.95", "yourPrice":"19.95"}
The back-end processing we can get figured out, but what is the best practice for a client submitting a discount code over a restful api?
Certain books will be eligible for discounts while others will not. Discounts will not be broad (20% off everything), but instead will map to a specific price for that particular code (or client/code combo).
We've considered:
kludging the url
GET /codes/{someCode}/books/{id}
Adding the code in a header value
Using a query string
GET /books?code=myCode
anything else?
EDIT: Our goal is not to implement single-use codes. Instead, these discount codes could be used some fixed number of times for some fixed set of books.
I like using query variables. I just looked at the RESTful Web Services book, my main reference in this area, and they say:
Use query variables only to suggest
arguments being plugged into an
algorithm... If two URIs differ only
in their query variables, it implies
they're the different sets of inputs
into the same underlying algorithm.
It seems to me your discount codes are inputs to a discounting algorithm.
Charles
If you're going to be submitting anything that's not idempotent, I would suggest using POST instead of GET. You wouldn't want a client to be able to use their code more than once.
Anything you add in the URL or header values are open to be intercepted, and possibly allowing other users to 'fake' their discount ID. 1 approach would be to introduce a new POST call, that will allow the ID to be encrypted with simple HTTPS. The POSTed data could be as simple as the discountID or customerID.
Added - Sorry Michael, you already said that :)
You can register the code in a table so when the user retrieves that book automatically returns that book with the proper discount, for example:
The user can add some code
POST /register/{code}
This will add an entry to a table {user} - {code} so when the user retrieves by
GET /books/{id}
will use that entry to apply the discount. I'm guessing that you already have some relation between {code}-{book} so wont get into that.