Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 8 years ago.
Improve this question
I have looked at many articles regarding REST and its design implementation for an API. I have a couple of questions however, and maybe they are simply opinionated as there is no "one fits all solution" to REST or API development in general.
Note that these questions are in regards to contacting and receiving requests from an SDK.
My questions are both in regards to the URI form, as I believe it is called. I have seen this represented in a few ways, but my big concern is about versioning and "dynamic" sections.
For my first question (version'ing) I have seen the following approached used often.
/customers/accounts/V3.4/customer_id/1234
/customers/accounts/V3.5/customer_id/1234
Developers would implement this by keeping a general version class, and as they make calls it would grab whatever version the developer has setup. So if they ever wanted to move up to a new API version they would just have to modify the V#.# in one location. I am wondering how good of an this idea is in practice, especially for an SDK. My general thoughts are that this is OK. I believe this as versions are clearly pointed out. If a change needs to be made it is simply a matter of updating your version's call. With an SDK in mind, using an old API won't break anything as if they do not update for awhile then their API request will still be fine, but will route through an older endpoint.
Question 1. Is version'ing using the approach above okay for API updates? Pro's/Cons?
The second question about dynamic values can be seen as follows.
/customers/V4.3/{customer_id}/account
versus
/customers/accounts/V3.4/customer_id/1234
I am not sure if there is a better trade-off to having dynamic endpoints versus hard coding them as listed above. I say this because what if we have a scenario where we wish to add details to the "account" page.
In the above example customers/V4.3 would not have to be updated, as it still contains the same user list midpoint. We would be able to update the account API without causing a version change. (forgive me if that is a terrible idea). But with the second option we would have to update the versioning as that is a midpoint
Question 2. In the example above, is it better to focus on more static or dynamic endpoints?
Still very new to learning about this, forgive me if I made some bad assumptions or conclusions on API design.
What is the problem with using Parameters ?
IMHO
Things that are dynamic or can change in future should never be part of the URL path.
This is why parameters exists. And the benefit is :-
http://example.com/api/resource/?customer_id=1234&v=3.4
Would be treated the same by your script as:-
http://example.com/api/resource/?v=3.4&customer_id=1234
I don't know the context of the SDK, but I would think hard about requirements before allowing API users to choose the version & perform actions.
Also please take a look https://stackoverflow.com/a/17999251/2489860
This is one of those RESTful debates that can go round in circles. You have three options for specifying the version: the URL, the content type or a custom header. All of them will be considered "wrong" by some folks.
Troy Hunt's written a pretty good discussion around the pros and cons here:
http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html
However, I wouldn't necessarily be too quick to reach for versioning as a solution. You may want to consider side-stepping the issue by using more tolerant consumers, investing in more up-front design or applying the open/closed principle to your APIs.
This argument is expressed in more detail here:
http://martinfowler.com/articles/enterpriseREST.html#versioning
It includes a great quote:
"Some people, when confronted with a problem, think "I know, I'll use versioning." Now they have 2.1.0 problems."
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 6 years ago.
Improve this question
I'm creating a sweepstakes application that is powered by an API. The hierarchy is fairly straightforward.
Clients
Users
Sweepstakes
Submissions
Clients can have users who are essentially admins of any sweepstakes. Clients can also have multiple sweepstakes. And a single sweepstakes can have multiple submissions. Okay, not complicated.
Where I get confused is what the correct approach is towards the URL structure. I've read documentation and best practice blogs all over the internet, and yet I'm still confused. Here are our current routes:
CLIENTS
POST /clients
GET /clients
GET /clients/:client_id
PUT /clients:client_id
USERS
POST /users
GET /users
GET /users/:user_id
PUT /users/:user_id
DELETE /users/:user_id
SWEEPSTAKES
POST /sweepstakes
GET /sweepstakes
GET /sweepstakes/:sweepstakes_id
PUT /sweepstakes/:sweepstakes_id
DELETE /sweepstakes/:sweepstakes_id
SUBMISSIONS
POST /submissions
GET /submissions
GET /submissions/:submission_id
PUT /submissions/:submission_id
DELETE /submissions/:submission_id
As you can see, I'm following a simple 2 URLs per resource -- what I feel is best practice. You can then drill into associations via query parameters on any GET request (e.g. /submissions?sweepstakes_id={sweepstakes_id}, /sweepstakes?client_id={client_id}, etc.).
This of course makes sense to me, however my co-worker and I are in a tiff because he is using Backbone to build the primary front-end app. Backbone states that they support RESTful API consumption off the bat, but my co-worker is telling me that Backbone prefers a URL structure that represents that hierarchal structure. I of course think that will leads to a messy, long, and overall confusing URL structure. Ideally, my co-worker would like to see the following URL structures:
GET /clients
GET /clients/users
GET /clients/sweepstakes
GET /clients/sweepstakes/submissions
Note: the above routes would also have additional routes to compliment single resources via an additional resource id in the URL (e.g. /clients/users/:user_id, /clients/sweepstakes/:sweepstakes_id/submissions, etc.).
I know this is somewhat of a touchy subject, but I'd love to hear some feedback on this. I vote for one 2 URLs per resource, and if any associations need to be made, they can be done so through the use of GET, or POST parameters. But I could be totally wrong.
You're right, this is a controversial topic. That being said I've found the gang at Apigee to be very helpful when trying to flesh out api standards/definition. They do not say that one way is correct, they more lean towards educated recommendations based off of their industry experience.
They offer some great resources and have some content that may help you get to a position where you can defend your opinion with someone else in your corner.
Check out this webinar... it is fairly basic stuff but always great for a refresher when it comes to api design.
note: I have no affiliation with Apigee, I just think that they have done some great work trying to get a standard defined for api design.
~ good luck and I hope this helps
I can't find anything in the official definition of REST that suggests that hierarchical URIs are preferred, but I may have missed something. I don't know anything about Backbone, but if it needs that structure I guess you have to do it, but there does not appear to be any reason why it would be better outside of that. However it is often preferred that each resource have one unique URI and the hierarchical one appears to have several. I know that you can't speak for your workmate, but has he offered any tangible reason why his scheme would have better functionality?
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 4 years ago.
Improve this question
With all the key value data stores out there I have started to create an abstraction layer so that a developer does not have to be tied in to a particular store. I propose to make libraries for:
Erlang
Ruby
Java
.NET
Does anyone have any tips on how I should go about designing this API?
Thanks
First off, and as a general rule for anytime you build "pluggable" abstraction layer, build it to support at least two real implementations to start. Don't build it for just one datastore and try to make it abstracted, because you'd overlook a details that won't plug into another implementation very well. By forcing it to use two seperate implementations, you'll get closer to something that is actually flexible, but you'll have to make further changes to support a third and fourth data store.
Second, don't bother, these things already exist. Microsoft has provided a ton of these for their technologies (ODBC, ADO, ADO.NET, etc), and I'm sure Ruby/Java/etc has several as well. I understand the desire to encapsulate the already existing technology, but the more data stores you need to support, the more complexity you need to build in, and the closer you'll get to ADO.NET (or similar technologies). Companies like MS have spent a ton of money and research on solving this exact problem, and that is what they came up with.
I would strongly recommend checking out Twitter's Storehaus project - this is a key-value store abstraction layer for the JVM and written in Scala, supporting (to date) Memcache, Redis, DynamoDB, MySQL, HBase, Elasticsearch and Kafka.
Storehaus's core module defines three traits:
A read-only ReadableStore with get, getAll and close
A write-only WritableStore with put, putAll and close
A read-write Store combining both
In the Ruby ecosystem, you should check out moneta, which again provides a unified interface to key/value stores. It has a lot more features than Storehaus.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Is it my browser that doesn't work with their API online documentation?
The structure of it seems to be very bad compared to the Java API online documentation and the Yii API online documentation.
I am new to Zend Framework, so I wonder, should it be like that?
I think the API is nice, the only problem sometimes they don't give real meaning of arguments
After the API is maybe a bit behind some java examples, but I find the reference guilde quiet impressive and complete. You've got 900 pages describing every piece of the framework with short code snippet that's just wonderful.
Personally I use more often the reference guide then the API documentation.
I've been digging into Zend Framework for about a month now. I'm starting to catch on but I have to agree with the initial comment. The API documentation, at least what is available, is atrocious. What is this Dojo stuff anyway? I would expect a proper, standardized API reference for something as extensive and powerful as the Zend Framework. For an experienced software engineer the reference manual is really introductory material. Once it is digested all that is really needed is a good API reference that clearly shows properties, methods, inheritance tree, with brief descriptions where necessary. Like Java, AS3, etc. I could have saved myself about two weeks of time had I had full access to the API. I don't get it, but I intend to persevere with ZF.
For me the problem is the reference guide simply lists through all the components and has a massive page telling very long-haul uses of each component with no sort of scope of where said code should appear in your work flow.
I believe it should be re-factored to be like CakePHPs documentation, where each page is targeted at getting a specific task done, like "Saving Your Data", "Deleting Data", "Validating Data" and so on.
Real life examples with context are a lot more useful then the Zend Docs where I tend to have to guess where certain variables (commonly $db) come from - and in full MVC cases, does't even apply.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
We have a project hand over from on shore team to our team (off shore) not long ago. However we were having difficulties for the hand-over process.
We couldn't think of any questions to ask during their design walk-through, because we were overwhelmed by the sheer amount of information. We wanted to ask, but we didn't know what to ask. Since they got no question from us, the management think that the hand-over process was been done successfully.
We had tried to go through all the documentation from our company wiki page before attending the handover presentation, but there are too many documents, we don't even know where to start with.
I wonder, are there any rules or best practices that we can follow, to ensure a successful project hand-over, either from us, or to us.
Thanks.
In terms of reading the documentation, personally I'd go for this order:
Get a short overview of the basic function of the application - what is it meant to achieve. The business case is probably the best document which will already exist.
Then the functional specification. At this point you're not trying to understand any sort of how or technology, just what the app is meant to do. If it's massive, ask them what they key business processes are and focus on those.
Then the high level technical overview. This should include an architecture diagram, required platforms, versions, config and so on. List any questions you have.
Then skim any other useful looking technical documents - certainly a FAQ if there is one, test scripts can be good too as they outline detailed "how to" type scenarios. Maybe it's just me but I find reading technical documents before I've seen the system a waste - it's too academic and they're normally shockingly written. It's certainly an area I'd limit the time I spent on if I didn't feel I was getting a reasonable return for the time I was spending.
If there are several of you arrage structured reviews between you and discuss the documents you've read, making sure you've got what you need to out of it. If the system is big then each take an area and present to the others on it - give yourselves a reason to learn as much as possible and knowing you're going to be quizzed is a good motivator. Make a list of questions where you don't understand something. Having structured reviews between you will focus your minds and make it more of an interactive task, rather than just trawling through page after page of tedious document.
Once you get face to face with them:
Start with a full system demo. Ask questions as they come up, don't let them fob you off with unclear answers - if they can't answer something have it written down and task them with getting the answer.
Now get the code checked out and running on your machines. Do this on at least two machines - one they lead, one you lead. Document the whole process - this is the most important step. If you can't get the code running you're screwed.
Go through the build process. Ensure that you can build the app (including any automated build and unit tests they may have). Note that all unit tests should pass - if they don't or if they say "oh, that one always fails" then they need to fix that before final acceptance.
Go through the install process. Do this at least twice, one they lead, once you lead. Make sure that it's documented.
Now come up with a set of common business functions carried out with the application. Use this to walk the code with them. The code base will be too big to cover the whole thing but make sure you cover a representative sample.
If there is a database or an API do a similar exercise. Come up with some standard data you might need to extract or some basic tasks you might need to carry out using the API and spend some time working through these with them.
Ask them if there's anything they think you should know.
Make sure that any questions you've written down anywhere else are answered.
You may consider it worth going through the bug list (open and closed) - start with the high priority ones and talk through anything particularly worrying looking. Even if they've fixed it it may point at a bit of code which is troublesome.
And finally if the opportunity exists - if there are any outstanding bugs or changes, see if you can pair program a couple.
Do not finally accept the app unless you are 100% sure you can:
Get the code to compile
Get the code to build (including the database)
Get the application installed
Do not accept handover is complete until they have:
Documented anything you picked up on that wasn't covered to your satisfaction
Answered ALL of your questions - a question they won't answer after being asked repeatedly screams of something they're hiding
And grab their e-mail addresses and phone numbers. Even if it's only informal they'll probably be willing to help out if the shit really hits the fan...
Good luck.
My basic process for receiving a handover would be:
Get a general overview of the app, document it
Get a list of all future work that the client expects
... all known issues
... any implementation specifics
As much up-to-date documentation they have
If possible, have them write some tests for critical components of the system (or at least get them thoroughly documented)
If there is too much documentation (possible) just confirm that it is all up to date, and make sure you find out from them where to start, if it is not clear.
Ask as many question as possible; anything that comes to mind, because you may not have the chance again.
Most handovers, perhaps all of them, will cause a lot of information to be lost. The only effective way to perform a handover that I have seen is to do it gradually. One way to do it is to allow a few key people from phase One to stay on the project well into Phase Two.
The extreme solution is to get rid of all handovers, and start using an Agile mindset.
As a start, define the exit criteria for the handover. This should be discussed, negotiated and agreed with both parties and make sure higher management knows this. Then write up a checklist of all things needed to achieve the exit criteria and chase it.
Check out "Software Requirements" and Software Requirement Patterns for ideas on questions to ask when gathering information about a project. I think that just as they would work for new development, they would also help you to come to terms with an existing project.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
What would you suggest for the following scenario:
A dozen of developers need to build and design a complex system. This design needs to be documented for future developers and the design decisions must be noted. These reports need to be made about every two months. My question is how this project should be documented.
I see two possibilities. Each developer writes about the things they helped design and integrate and then one person combines each of these documents together. The final document will probably be incoherent or redundant at times since the person tasked of assembling everything won't have much time to adjust every part.
Assume that the documentation parts from each developer arrive just a few days before deadline. A collaborative system (i.e. wiki) wouldn’t work properly since there wouldn’t be anything to read until a few days before deadline.
Or should a few people (2-3) be tasked with writing the documentation while the rest of the team works on actually developing the system? The developers would need a way to transfer their design choices and conclusions to the technical writers. How could this be done efficiently?
We approach this from 2 sides, using a RUP style approach. In the first case, you'll have a domain expert who is responsible for roughing out the design of what you're going to deliver - with developers chipping in as necessary. In the second case, we use a technical author - they document the application, so they should have a good idea of how it hangs together, and you involve them right through the design and development process. In this case, they can help to polish the design, and to make sure that it matches what they thought was being developed.
We use confluence (atlassian's wiki-like-thing) and document all kinds of different "things". The developers do it continiously, and we push each other for docs - we let peer pressure decide what is necessary. Whenever someone new comes along he/she is tasked with reading through everything and to find out what still is correct. The incorrect stuff is either deleted or updated as a consequence of this. We're happy when we can delete stuff ;)
The nice thing about this process is that the relevant stuff stays and the irrelevant stuff is deleted. We always "got away" from the more formalized demands by claiming that we could always construct the word documents they wanted if "they" needed them. "They" never needed them.
I think alternative 2 is the less agile, because it means a new stage to the project (although it may be in parallel with tests).
If you are in an agile model, then just add documentation (following a guideline) as a story.
If you are in a staged approach, then I would nevertheless ask developers to work on documentation, following some guidelines, and review that documentation along the design and the code. Eventually, you may have a technical writer reviewing everything for proper English, but that would be a kind of "release" activity.
I think you can use Sand Castle to document your project.
Check it out
Sand Castle from Microsoft
It's not a complete documentation, but making sure that interfaces etc. are commented using Doxygen-style comments means writing code and documenting it are closer together.
That way, developers should document what they do. I still think a review by the architect(s) is needed to ensure consistent quality, but ensuring people document what they do is the best way to ensure they follow the architecture.