Many things can have phone numbers and addresses. . . people, places, etc. You want phone numbers and addresses to have the same functionality, format and validation whether it is a phone number or address for a person or a place etc.
Is it going to far to create a phone number class, and an address class, and use them in those objects that have phone numbers and addresses?
My question goes to other properties as well that could be reuseable across diverse objects.
Yes, you can go too far and this is borderline. I tend to draw the line at the point where it becomes cumbersome to treat things as more than a string, or another already defined class/type.
If you need to somehow manipulate phone numbers (by, for example, separating them into area code and other bits) or addresses (number, street, city, country and so forth) then, yes, consider making them objects.
I rarely do anything with phone numbers or addresses other than store and display them, in which case they're fine as strings without having to have their own dedicated class. For addresses, I don't even impose a separation based on parts (except maybe the zipcode), preferring free-format entry so as to not annoy those with addresses of a format I don't know about.
Going the reductio ad absurdum route, you could also objectify the characters that make up your phone number but that would be silly.
I think it would be perfectly acceptable. A well designed class will allow you to reuse it in many different projects. If you have many projects that could use this sort of functionality, using an object is the perfect way to ensure that your code is reusable and portable. The extensibility and the potential for you to extend the functionality of your class to handle anything phone number/address related would be unmatched by a set of functions or once off code you rewrite over and over.
In the end it's your call, personally I think it would fall under good practice though.
You need an Entity Class and Address Class.
Entity can be person, place, organisation, coffee shop kinda, whereas Address can capture Phone number, emailid, Lat/Long kinda stuff.
Keeping Entity and Address will help you across diverse objects.
and having many to many relation ship among entity and address would help, having loose coupling wud help on long run.
Related
Background
I have 2 resources: courses and professors.
A course has the following attributes:
id
topic
semester_id
year
section
professor_id
A professor has the the following attributes:
id
faculty
super_user
first_name
last_name
So, you can say that a course has one professor and a professor may have many courses.
If I want to get all courses or all professors I can: GET /api/courses or GET /api/professors respectively.
Quandary
My quandary comes when I want to get all courses that a certain professor teaches.
I could use either of the following:
GET /api/professors/:prof_id/courses
GET /api/courses?professor_id=:prof_id
I'm not sure which to use though.
Current solution
Currently, I'm using an augmented form of the latter. My reasoning is that it is more scale-able if I want to add in filtering/sorting criteria.
I'm actually encoding/embedding JSON strings into the query parameters. So, a (decoded) example might be:
GET /api/courses?where={professor_id: "teacher45", year: 2016}&order={attr: "topic", sort: "asc"}
The request above would retrieve all courses that were (or are currently being) taught by the professor with the provided professor_id in the year 2016, sorted according to topic title in ascending ASCII order.
I've never seen anyone do it this way though, so I wonder if I'm doing something stupid.
Closing Questions
Is there a standard practice for using the query string vs the resource path for filtering criteria? What have some larger API's done in the past? Is it acceptable, or encouraged to use use both paradigms at the same time (make both endpoints available)? If I should indeed be using the second paradigm, is there a better organization method I could use besides encoding JSON? Has anyone seen another public API using JSON in their query strings?
Edited to be less opinion based. (See comments)
As already explained in a previous comment, REST doesn't care much about the actual form of the link that identifies a unique resource unless either the RESTful constraints or the hypertext transfer protocol (HTTP) itself is violated.
Regarding the use of query or path (or even matrix) parameters is completely up to you. There is no fixed rule when to use what but just individual preferences.
I like to use query parameters especially when the value is optional and not required as plenty of frameworks like JAX-RS i.e. allow to define default values therefore. Query parameters are often said to avoid caching of responses which however is more an urban legend then the truth, though certain implementations might still omit responses from being cached for an URI containing query strings.
If the parameter defines something like a specific flavor property (i.e. car color) I prefer to put them into a matrix parameter. They can also appear within the middle of the URI i.e. /api/professors;hair=grey/courses could return all cources which are held by professors whose hair color is grey.
Path parameters are compulsory arguments that the application requires to fulfill the request in my sense of understanding otherwise the respective method handler will not be invoked on the service side in first place. Usually this are some resource identifiers like table-row IDs ore UUIDs assigned to a specific entity.
In regards to depicting relationships I usually start with the 1 part of a 1:n relationship. If I face a m:n relationship, like in your case with professors - cources, I usually start with the entity that may exist without the other more easily. A professor is still a professor even though he does not hold any lectures (in a specific term). As a course wont be a course if no professor is available I'd put professors before cources, though in regards to REST cources are fine top-level resources nonetheless.
I therefore would change your query
GET /api/courses?where={professor_id: "teacher45", year: 2016}&order={attr: "topic", sort: "asc"}
to something like:
GET /api/professors/teacher45/courses;year=2016?sort=asc&onField=topic
I changed the semantics of your fields slightly as the year property is probably better suited on the courses rather then the professors resource as the professor is already reduced to a single resource via the professors id. The courses however should be limited to only include those that where held in 2016. As the sorting is rather optional and may have a default value specified, this is a perfect candidate for me to put into the query parameter section. The field to sort on is related to the sorting itself and therefore also belongs to the query parameters. I've put the year into a matrix parameter as this is a certain property of the course itself, like the color of a car or the year the car was manufactured.
But as already explained previously, this is rather opinionated and may not match with your or an other folks perspective.
I could use either of the following:
GET /api/professors/:prof_id/courses
GET /api/courses?professor_id=:prof_id
You could. Here are some things to consider:
Machines (in particular, REST clients) should be treating the URI as an opaque thing; about the closest they ever come to considering its value is during resolution.
But human beings, staring that a log of HTTP traffic, do not treat the URI opaquely -- we are actually trying to figure out the context of what is going on. Staying out of the way of the poor bastard that is trying to track down a bug is a good property for a URI Design to have.
It's also a useful property for your URI design to be guessable. A URI designed from a few simple consistent principles will be a lot easier to work with than one which is arbitrary.
There is a great overview of path segment vs query over at Programmers
https://softwareengineering.stackexchange.com/questions/270898/designing-a-rest-api-by-uri-vs-query-string/285724#285724
Of course, if you have two different URI, that both "follow the rules", then the rules aren't much help in making a choice.
Supporting multiple identifiers is a valid option. It's completely reasonable that there can be more than one way to obtain a specific representation. For instance, these resources
/questions/38470258/answers/first
/questions/38470258/answers/accepted
/questions/38470258/answers/top
could all return representations of the same "answer".
On the /other hand, choice adds complexity. It may or may not be a good idea to offer your clients more than one way to do a thing. "Don't make me think!"
On the /other/other hand, an api with a bunch of "general" principles that carry with them a bunch of arbitrary exceptions is not nearly as easy to use as one with consistent principles and some duplication (citation needed).
The notion of a "canonical" URI, which is important in SEO, has an analog in the API world. Mark Seemann has an article about self links that covers the basics.
You may also want to consider which methods a resource supports, and whether or not the design suggests those affordances. For example, POST to modify a collection is a commonly understood idiom. So if your URI looks like a collection
POST /api/professors/:prof_id/courses
Then clients are more likely to make the associate between the resource and its supported methods.
POST /api/courses?professor_id=:prof_id
There's nothing "wrong" with this, but it isn't nearly so common a convention.
GET /api/courses?where={professor_id: "teacher45", year: 2016}&order={attr: "topic", sort: "asc"}
I've never seen anyone do it this way though, so I wonder if I'm doing something stupid.
I haven't either, but syntactically it looks a little bit like GraphQL. I don't see any reason why you couldn't represent a query that way. It would make more sense to me as a single query description, rather than breaking it into multiple parts. And of course it would need to be URL encoded, etc.
But I would not want to crazy with that right unless you really need to give to your clients that sort of flexibility. There are simpler designs (see Roman's answer)
I am building a small application for an english speaking client in Japan. As part of the app, users need to be able to enter their address. Unfortunately, I can't find any reference for how addresses are usually handled in an online form.
I know that there are different combinations of wards/prefectures/cities; do these all usually have their own field in a database? Is it standard for all of that to go into a general "city" type of field? What's the standard UI for this sort of thing?
The Universal Postal Union has compiled info on address formats in different countries. See also an unofficial guide to postal addresses.
But as a rule, internationalization of software typically means that for postal addresses, you avoid imposing any specific format. Instead, you would use a free-form text input area, of sufficient size. There are often many forms of addresses used in a country (and Japan is no exception), and normally you need not enforce any specific format – instead, you expect people to know their own address and how to enter it so that postal services can understand it.
it depends on what you have to do with the address:
if you have to:
check for obligatory fields
validate fields, or
query for city, prefecture, postal code, etc.
then you should use separate fields. UI: a form with text-inputs (and maybe even menus).
do not use more fields than necessary, so if you don't have any of the mentioned needs, just use a text-field (UI: textarea).
The first part of a Japanese address is easy: Todofuken will either be 2 or 3 characters, followed by either "都","道","府" or "県". Where it gets tricky is the rest of the address since smaller areas don't always divide their cities neatly.
What I've seen to make this easier is using the postal code to render the address. The bad news is that I haven't seen any of this in Ruby but I have seen it in other languages so hopefully this will help.
This site is only in Japanese, but maybe you can download the code and check it out:
http://www.kawa.net/works/ajax/ajaxzip2/ajaxzip2.html
There's also this add-in for Excel that converts addresses. The code may be helpful to you:
http://office.microsoft.com/ja-jp/excel-help/HP010077514.aspx
Hope this helps.
I am trying to really get a good idea how to think in OOP terms, so I have a semi-hypothetical scenario in my mind and I was looking for some thoughts.
If I wanted to design a simulation for different types of people interacting with each other, each of whom could acquire different proficiency levels in different "skills", what would be an optimal way to do this?
It's really the "skills" thing that I was a bit caught up on. My requirements are as follows:
-Each person either "has" a skill or does not
-If people have skills, they also have a "proficiency level" associated with the skill
-I need a way to find and pick out every person that has certain skills at all, or at a certain level
-The design needs to be extendible (ie, I need to be able to add more "skills" later)
I considered the following options:
have a giant enum for every single skill I include, and have the person class contain an
"int Skills[TOTAL_NUM_SKILLS]" member. The array would have zeros for "unacquired" skills, and 1 to (max) for proficiency levels of "acquired skills".
have the same giant enumeration, and have the person class contain a map of skills (from the enum) and numbers associated with the skills so that you can just add only the acquired skills to the map and associate a number this way.
Create a concrete class for every single skill, and have each inherit from an abstract base class (ISkill, say), and have the person class have a map of ISkill's
Really, option 1 seems like the straightforward no-nonsense way to do it. Please criticize; is there some reason this is not acceptable? Is there a more object oriented way to do this?
I know that option 3 doesn't make much sense right now, but if I decided to extend this later to have skills be more than just things with proficiency associated with them (ie, actually associate new actions with the skills (ISkill::DoAction, etc), does this make sense as an option?
Sorry for the broad question, I just want to see if this line of thought makes sense, or if I'm barking up the wrong tree altogether.
The problem with option 1 is future compatibility. Say you were shipping this framework to customers. Now, the customer has built this array of Skill values, which is length TOTAL_NUM_SKILLS, for each person. But this fails as soon as you try to add another skill, and especially as you try to reorder skills.
What if the customer is using an RPC framework in which a client and server pass Person objects over the wire? Now, unless the customer upgrades the client and server at the exact same time, the RPC calls break, since now the client and server expect arrays of different lengths. This can be particularly tricky because the customer may own only the client, or only the server, and be unable to upgrade both at once.
But it gets worse. Say the client has written out a Person object to disk in some file. If they decided to serialize a person as a simple list of numbers, then a new skill will cause the deserialization code to fail. Worse, if you reorder skills in your enum, the deserialization code may work just fine but give a wrong answer.
I like option 3 exactly for the reason you named: later you can add more functionality, and do so safely (well, except for the fact that every public change is a breaking change if your customers exercised certain edge cases in the language).
If you want to add skills often without changing the overall program structure, I'd consider some kind of external data file that you can change without recompiling your code. Think about how you'd want to do it in a really large project. The person who chooses the skills might be a designer with no programming ability. He could edit the skills in an XML file, but not in C++ code.
If you defined the skills in XML, it would naturally extend to store more data with each skill. Your players could be serialized as XML files too.
When you set up a player's skills at runtime, you could build a hash table keyed on the skill name from the XML file. If it's more common to enumerate a player's skills than to query whether a player has a certain skill, you could just use a vector of strings.
Of course, this solution will use more memory and run slower than your enum solution. But it will probably be good enough unless you're dealing with millions of players in your program.
Soliciting feedback/thoughts on a pattern or best practice to address a situation that I have seen a few times over the years, yet I haven't found any one solution that addresses it the way I'd like.
Here is the background.
Company has 3 applications supporting 3 separate "lines of business" that are very much related to each other. Two of the applications are literally copy/paste from the original. The applications need to be able to grow at different rates and have slightly different functionality. The main differences in functionality come from the data entry fields. The differences essentially fall into one of the following categories:
One instance has a few fields
that the other does not.
String field has a max length of 200 in one
instance, but 50 in another.
Lookup/Reference fields have
different underlying values (i.e.
same table structures, but coming
from different databases).
A field is defined as a user supplied,
free text, value in one instance,
but a lookup/reference in another.
The problem is that there are other applications within the company that need to consume data from these three separate applications, but ideally, talk to them in a core/centralized manner (i.e. through a central service rather than 3 separate services). My question is how to handle, in particular, item D above. I am thinking a "lowest common denominator" approach might be the only way. For example:
<SomeFieldName>
<Code></Code> <!-- would store a FK ref value if instance used lookup, otherwise would be empty or nonexistent-->
<Text></Text> <!-- would store the text from the lookup if instance used lookup, would store user supplied text if not-->
</SomeFieldName>
Other thoughts/ideas on this?
TIA!
So are the differences strictly from a Datamodel view or are there functional business / behavioral differences at the application level.
If the later is the case then I would definetly go down the path you appear to be heading down with SOA. Now how you impliment your SOA just depends upon your architecture needs. What I would look at for design would be into some various patterns. Its hard to say for sure which one(s) would meet the needs with out more information / example on how the behavioral / functional differences are being used. From off of the top of my head tho with what you have described I would probably start off looking at a Strategy pattern in my initial design.
Definetly prototype this using TDD so that you can determine if your heading down the right path.
How about: extend your LCD approach, put a facade in front of these systems. devise a normalised form of the data which (if populated with enough data) can be transformed to any of the specific instances. [Heading towards an ESB here.]
Then you have the problem, how does a client know what "enough" is? Some kind of meta-data may be needed so that you can present a suiatble UI. So extend the services to provide an operation to deliver the meta data.
I am designing a contact management system and have come across an interesting issue regarding modeling geographic locations in a consistent way. I would like to be able to record locations associated with a particular person (mailing address(es) for work, school, home, etc.) My thought is to create a table of locales such as the following:
Locales (ID, LocationName, ParentID) where autonomous locations (such as countries, e.g. USA) are parents of themselves. This way I can have an arbitrarily deep nesting of 'political units' (COUNTRY > STATE > CITY or COUNTRY > STATE > CITY > UNIVERSITY). Some queries will necessarily involve recursion.
I would appreciate any other recommendations or perhaps advice regarding predictable issues that I am likely to encounter with such a scheme.
You might want to have a look at Freebase.com as a site that's had some open discussion about what a "location" means and what it means when a location is included in another. These sorts of questions can generate a lot of discussion.
For example, there is the obvious "geographic nesting", but there are less obvious logical nestings. For example, in a strictly geographic sense, Vatican City is nested within Italy. But it's not nested politically. Similarly, if your user is located in a research center that belongs to a university, but isn't located on the University's property, do you model that relationship or not?
Sounds like a good approach to me. The one thing that I'm not clear on when reading you post is what "parents of themselves" means - if this is to indicate that the locale does not have a parent, you're better off using null than the ID of itself.
I think you might be overthinking this. There's a reason most systems just store addresses and maybe a table of countries. Here are some things to look out for:
Would an address in the Bronx include the borough as a level in the hierarchy? Would an address in an unincorporated area eliminate the "city" level of the hierarchy? How do you model an address within a university vs an address that's not within one? You'll end up with a ragged hierarchy which will force you to traverse the tree every time you need to display an address in your application. If you have an "address book" page the performance hit could be significant.
I'm not sure that you even have just one hierarchy. Brown University has facilities in Providence, RI and Bristol, RI. The only clean solution would be to have a double hierarchy with two campuses that each belong to their respective cities in one hierarchy but that both belong to Brown University on the other hierarchy. (A university is fundamentally unlike a political region. You shouldn't really mix them.)
What about zip codes? Some zip codes encompass multiple towns, other times a city is broken into multiple zip codes. And (rarely) some zip codes even cross state lines. (According to Wikipedia, at least...)
How will you enter the data? Building out the database by parsing conventionally-formatted addresses can be difficult when you take into account vanity addresses, alternate names for certain streets, different international formats, etc. And I think that entering every address hierarchically would be a PITA.
It sounds like you're trying to model the entire world in your application. Do you really want or need to maintain a table that could conceivable contain every city, state, province, postal code, and country in the world? (Or at least every one where you know somebody?) The only thing I can think of that this scheme would buy you is proximity, but if that's what you want I'd just store state and country separately (and maybe the zip code) and add latitude and longitude data from Google.
Sorry for the extreme pessimism, but I've gone down that road myself. It's logically beautiful and elegant, but it doesn't work so well in practice.
Here's a suggestion for a pretty flexible schema. An immediate warning: it could be too flexible/complex for what you actually need
Location
(LocationID, LocationName)
-- Basic building block
LocationGroup
(LocationGroupID, LocationGroupName, ParentLocationGroupID)
-- This can effective encapsulate multiple hierarchies. You have one root node and then you can create multiple independent branches. E.g. you can split by state first and then create several sub-hierarchies e.g. ZIP/city/xxxx
LocationGroupLocation
(LocationID, LocationGroupID)
-- Here's how you link Location with one or more hierarchies. E.g. you can link your house to a ZIP, as well as a City... What you need to implement is a constraint that you should not be able to link up a location with any two hierarchies where one of them is a parent of the other (as the relationship is already implicit).
I would think carefully about this since it may not be a necessary feature.
Why not just use a text field and let users type in an address?
Remember the KISS principle (Keep It Simple, Stupid).
I agree with the other posts that you need to be very careful here about your requirements. Location can become a tricky issue and this is why GIS systems are so complicted.
If you are sure you just need a basic heirarchy structure, I have the following suggestions:
I support the previous comment that root level items should not have themselves as the parent. Root level items should have a null value for the parent. Always be careful about putting data into a field that has no meaning (i.e. "special" value to represent no data). This practice is rarely necessarily and way overused in the devleoper community.
Consider XPath / XML. This is Something to consider for bother recording the heirarchy structure, and for processing / parsing the data at retrieval. If you are using MSSQL Server, the XPath expressions in select statements are perfect for tasks such as returning the full location/heirarchy path of a record as the code is simple and the results are fast.
For Geographic locations you may wish to resolve an address to a Latitude, Longitude array (perhaps using Google maps etc.) to calculate proximities etc.. For Geopolitical nesting ... I'd go with the KISS response.
If you really want to model it, perhaps you need the types to be more generic ... Country -> State -> County -> Borough -> Locality -> City -> Suburb -> Street or PO Box -> Number -> -> Appartment etc. -> Institution (University or Employer) -> Division -> Subdivision-1 -> subdivision-n ... Are you sure you can't do KISS?
I'm modeling an apps for global users and I have the same problems, but I think that this approach could already be in use in many enterprise. But why this problem don't have an universal solution? Or, has this problem one best solution that can be the start point or anybody in the world need think in a solution for it since beginnig?
In IT, we are making the same things any times and in many places, unfortunately. For exemplo, who are not have made more than one user, customer or product's database? And the worst, all enterprise in the world has made it. I think that could have universal solutions for universal problems.