This is a REST web service that can be used to manage a rubric through the net.
Endpoint: https://truecloud.ddns.net:8080/contacts/api/
When data needs to be transfered into the HTTP request body (e.g. POST, PUT requests) it must be defined using the JSON language.
To make a request the user must be authenticated by the web service server. In order to do so, the user must provide its credentials into the HTTP Authorization header. The header type is Basic and the credentials have to be specified after the "Basic" string separeted by a column (username:password). This string (without "Basic") must be encoded with a base 64 encoding and the password mustn't be sent in clear, but its digest, calculated with a SHA-256 function, has to be provided, instead.
- GET: to get data from the service
- POST: to create new resources
- PUT: to modify an existing resource
- DELETE: to delete a resource
- OPTION: to get the list of all supported HTTP methods
| Path | Parameters | Result |
|---|---|---|
| /contacts/ | Returns all the contacts owned by the user who is making the request | |
| /contacts/{contactId} | contactId: the id of a contact | Returns a specific contact, but only if that contact belongs to the user who is making the request |
| /groups/ | Returns all the groups owned by the user who is making the request | |
| /groups/{groupid} | groupId: id of a specific group | Returns a specific group, but only if that group belongs to the user who is making the request |
| /groups/{groupId}/contacts/ | groupId: id of a specific group | Returns all the contats of a specific group, but only if the group belongs to the user who is making the request |
| /calls/ | Returns all the calls made and received by the user who is making the request | |
| /calls/{callId}/ | callId: id of a specific call | Returns a specific call, but only if it has been made or received by the user who is making the request |
If the id provided doesn't identify any resource or if the resource identified cannot be returned (e.g. if the resource belongs to another user) then the response status code will be 404 Not Found, otherwise the resource's JSON encoding is returned and the status code will be 200 OK.
| Path | Parameters | Result |
|---|---|---|
| /users/ | Only login request | Test the user's credentials |
| /users/ | Contact definition | Creates a new user and the associated contact |
| /contacts/ | Contact definition | Creates a new contact and sets as owner the user who is making the reqest |
| /contacts/{contactId}/phoneNumbers/ |
contactId: id of a specific user List of phone numbers |
Creates new phone numbers and associates them to the contact identified by the id, but only if the contact belongs to the user who is making the request |
| /contacts/{contactId}/emails/ |
contactId: id of a specific user List of emails |
Creates new email addresses and associates them to the contact identified by the id, but only if the contact belongs to the user who is making the request |
| /groups/ | Group definition | Creates a new group, but only if the group owner specified is the same user that is making the request |
| /groups/{groupId}/contacts/ |
groupId: id of a specific group List of contacts to insert into the group |
Inserts some contacts into a specific group, but only if the group and the contacts belong to the user who is making the request |
| /calls/ | Call definition | Inserts a call made by a contact, but only if that contact is associated to the user who is making the request |
When the resource has been created it id is returned into the Location header of the response message and 210 Created will be the status code.
If an error occurs when the user tries to create a new contact or add new phone numbers or email addresses to a contact, then a list of all numbers or email addresses not entered successfully is returned.
| Path | Parameters | Result |
|---|---|---|
| /users/ | New user's credentials | Modifies the credentials of the user who is making the request |
| /contacts/{contactId}/ | Contact definition | Substitutes the old contact with a new one, but only if the contact belongs to the user who is making the request |
| /contacts/{contactId}/phoneNumbers/{phoneId} |
contactId: id of a specific contact phoneId: id of a specific phoneNumber Phone number definition |
Substitutes one of the phone numbers of a contact with another, but only if the contact belongs to the user who is making the request |
| /contacts/{contactId}/emails/{email} |
contactId: id of a specific contact email: old email Email definition |
Substitutes one of the emails of a contact with another, but only if the contact belongs to the user who is making the request |
| /groups/{groupId} |
groupId: id of a specific group Group definition |
Modifies the name of a group, but only if the group belongs to the user who is making the request |
When the email of the phone number of a contact is modified the resource is not really modified, it is subtituted with an already existing one o with a new one created in the moment of the request, so the resource id has to be updated with a GET request.
| Path | Parameters | Result |
|---|---|---|
| /users/ | Deletes the user who is making the request | |
| /contacts/{contacId} | contactId: id of a specific contact | Deletes a specific contact, but only if it belongs to the user who is making the request |
| /contacts/{contacId}/phoneNumbers/{phoneId} |
contactId: id of a specific contact phoneId: id of a specific phone number |
Deletes a phone number associated to a contact, but only if the contact belongs to the user who is making the request |
| /contacts/{contactId}/emails/{email} |
contactId: id of a specific contact email: email |
Deletes an email address associated to a contact, but only if the contact belongs to the user who is making the request |
| /groups/{groupId} | groupId: id of a specific group | Deletes a group, but only if it belongs to the user who is making the request |
| /groups/{groupId}/contacts/{contactId} |
groupId: id of a specific group contactId: id of a specific contact |
Removes a contact by a group, but only if the group belongs to the user who is making the request |
When a resource is successfully deleted, 204 No Content is returned.
The json representation of all the resources uses the properties name as the key. When providing a resource definition it must not be put into the root of the json document, instead, it must be assigned to a field that has the same name of the resource (e.g. if creating a group, the group definition must be assigned to a field named group), or the plural name if a collection of resources is being provided (e.g. if adding phone numbers to a contact, every phone number definition must be put into an array and the array must be assigned to a field named phoneNumbers).
| Property | Description |
|---|---|
| The emaild used to identify the user | |
| password | The digest calculated with a SHA-256 function of the password used by the user to authenticate |
Except when registering a new user, password field can be omitted.
| Property | Description |
|---|---|
| id | The resource identifier of the phone number |
| countryCode | The national identifier of the phone number (e.g. for Italy it is +39) |
| areaCode | Reading the phone number from left to right this represent the first 3 digits |
| prefix | Reading the phone number from left to right this represent the second group of 3 digits |
| phoneLine | The last 4 digits of the phone number |
| description | A word or a short phrase that describes the phone number (e.g. Office, school, house, ...) |
The country code must be provided without the + character.
When creating a phone number all the fields must be provided except for id and description.
| Property | Description |
|---|---|
| The email address | |
| description | A word or a short phrase that describes the email address (e.g. Office, school, personal ...) |
| Property | Description |
|---|---|
| id | The resource identifier of the contact |
| firstName | The first name of the contact |
| familyName | The family name or surname of the contact |
| secondName | The second name of the contact |
| owner | The user who this contact belongs to |
| associatedUser | If this contact is the representation of a user this property holds the user's credentials |
| phoneNumbers | An array that holds all the phone numbers associated to the contact |
| emails | An array that holds all the email addressed associated to the contact |
To the fields owner and associateUser it must be assigned an object of type User. In the same way to phoneNumbers and emails it must be assigned and array of objects of type PhoneNumber and Email.
When creating a new contact firstName, familyName and owner fields must be specified, while the other can be null. Of course, when creating a new user the id field doesn't have a value.
| Property | Description |
|---|---|
| id | The resource identifier of the group |
| name | The name of the group |
| owner | The user who has created this group that is the user who this group belongs to |
| contacts | An array that holds all the contacts of the group |
As before, owner is an object of type User and contacts is an array of objects of type Contact.
When creating a group values for name and owner fields must be provided.
| Property | Description |
| Id | The resource identifier of the call |
| callerNumber | The numbers that has made the call |
| callerContact | The contact who has made the call |
| calledNumber | The number that has been called |
| calledContact | The contact who has been called |
| timestamp | Date and time in which the call has been made |
| duration | Duration in seconds of the call |
When the user wants to send a request to just test its credentials it has to send a POST request in which the user's credentials are provided via the Authorization header and the body must contain this json code:
{
"justLogin": true
}When registering a new user, credentials don't have to be inserted into the Authorization header, instead, In the body of the request, it must be defined a new contact that has the user's credentials as value for the owner and associatedUser fields.
{
"contact": {
"firstName": "Gennaro",
"familyNam": "Rossi",
"secondName": null,
"owner": {
"email": "[email protected]",
"password": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
},
"associatedUser": {
"email": "[email protected]",
"password": "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
},
"phoneNumber": [],
"emails":[]
}
}| Status code | Meaning |
|---|---|
| 200 OK | In get requests it indicates that the resource has been returned, while when logging in it indicates that the credentials are valid |
| 201 Created | In POST requests it indicates that the resource has been successfully created |
| 204 No Content | In PUT and DELETE requests it indicates that the resource has been sucessfully updated or deleted |
| 400 Bad Request | The request has not been accepted due to an error |
| 401 Unauthorized | The credentials are missing or wrong or the resource belongs to another user so the request cannot be accepted |
| 404 Not Found | The request cannot be accepted because it requires one or more resources that don't exist |
| 409 Conflict | In PUT and DELETE requests it indicates that the rescource has not been updated or deleted due to an error |
If the status code indicates that the request has not been successfully resolved an error message will be provided as the body of the response
| Field | Description |
|---|---|
| type | It can be error, warning or info and it indicates the severity of the error |
| code | A numeric value that indicates the type of error returned |
| title | A brief description of the kind of error that has occured |
| message | A more detailed description of the error and probable causes |
| suggestion | A suggestion to resolve the error or find out its causes |
| data | Additional useful information to resolve the error |
Every error message has the same structure, only the data filed may not be present because it is only used in certain circumstances.
| Error code | Error name | Description |
|---|---|---|
| 1 | Registration Failure | An error occured while trying to register a new user |
| 2 | Duplicated User | You tried to register a new user, but the email is already assigned to another one |
| 3 | Missing Authenticaction | Credentials have not been provided, or the Authorization header type is not Basic |
| 9 | Failed Authentication | The credentials provided are wrong |
| 10 | Credentials Mismatch | The credentials used to authenticate are different from the one indicated in the owner or associatedUser field of the resource |
| 8 | Invalid Content Type | The Content-Type header is wrong |
| 18 | Invalid character encoding | The charset specified int the Content-Type header is wrong |
| 19 | Missing Content-Type header | The Content-Type header has not been specified |
| 4 | Wrong Syntax | There are some syntax error in the json text or the needed data has not been provided |
| 5 | Insertion Failure | An error has occured while trying to create a new resource |
| 6 | Missing URL Component | The URL is incomplete |
| 7 | Wrong URL component | One or more components of the URL are wrong or invalid |
| 11 | Wrong Object Id | The id provided to identify the resource is invalid and cannot be used |
| 17 | Inacessible Or Non-existing Resource | The id provided doesn't identify any resource or you don't have the authorization needed to access that resource (e.g. the resource belongs to another user) |
| 12 | Data Not Modifiable | The resource cannot be modifies because the new resouce is identical to the old one |
| 13 | Data Not Modified | An error has occured while trying to modify a resource |
| 14 | Deletion Unathorized | The deletion cannot be accomplished because the resource belongs to another user |
| 15 | Deletion Failed | An error has occured while trying to delete a resource |
| 16 | Deletion Not Allowed | The deletion has failed because the resource cannot be deleted (e.g. the contact associated to a user cannot be deleted without deleting the user too) |