API planning

General comments

In the long run DiMe should perhaps follow Principles of good RESTful API Design, for example using PUT and PATCH for updating existing objects instead of POST'ing with the id given. But for now we'll stick with the old way in order to be consistent with the rest of the DiMe API.

Also API versioning should be introduced at some point, e.g. /api/v1, /api/v2 and so on.

General stuff

These are DiMe-specific things, not user account specific, and thus do not require authentication.

GET /api/ping
GET /api/dime_id

Profile API

POST api/profile (adding new profile, profile name response: profile ID)
POST api/profile (modifying a profile if the ID is given in the posted data)
GET api/profile/{ID} (get the content of profile, what is in the profile?)
DELETE api/profile/{ID} (deleting obviously)

Example

POST api/profile with the data:

{
  name: “Kai’s formula profile”,
  search_keywords: [“x”, “y”, ],
  tags: ["tag1", "tag2"],	
}

DiMe response:

{
  id: 83724, 
  name: “Kai’s formula profile”,
  search_keywords: [“x”, “y”, ],
  tags: ["tag1", "tag2"],	
}

/profile/:id/addevent
{
    "event": {
        "@type": "SearchEvent",
        "id": 728,
    },
    "weight": 0.5,
    "actor": "FooAlgorithm",
}

/profile/:id/addevents
[...]

/profile/:id/addinformationelement
{
    "informationelement": {},
    "weight": 0.5,
    "actor": "FooAlgorithm",
}

Access profile:

{
  name: "Kai's formula profile",
  search_keywords: ["x", "y" ],
  tags: ["tag1", "tag2"],
  validated_events: [
    {
      "event": { ...
      }
      "weight": 1.0,
      "actor": "FooAlgorithm",
      "validated": true,
    },
    {
     ...
    }
  ]
      
  suggested_events: [
    {
      "event": { ...
      }
      "weight": 0.5,
      "actor": "FooAlgorithm",
      "validated": false,
    }
  ]
} 

on validation: keep event in suggested_events, set validated=true, add new event to validated_events

/profile/:id/validate_event
{
      "event": { ...
      }
      "weight": 0.5,
      "interface": "My DiMe UI",
    }
}

Model API

register model (register name, get ID?)

Tag API

Get list of n most common tags.

GET /api/tag/most_common

[{
  id: 38093,
  name: "reknow",
  eventsCount: 30,
  elementsCount: 28,
  actors: ["KEA 1.0", "lucene"],
  lastAdded: timestamp,
},
]

Get events for tag with given id

GET /api/tag/events/38093
GET /api/tag/informationelements/38093

Account API

Create Account

POST /api/accounts

Posted JSON Object

{
  "username":"testuser",
  "password":"testuser123",
  "email":"[email protected]"
}

curl

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"testuser123","email":"[email protected]"}' \
  http://<SERVER_HOST>/api/accounts

HTTP response headers:

Status: 201 Created
Location: http://<SERVER_HOST>/api/accounts/<account_id>

HTTP response body:

{
  "timeCreated": 1430142736819,
  "accountId": 1
}

Update an account

PUT /api/accounts/<account_id>

curl

curl -X PUT \
  -u username:password \
  -H "Content-Type: application/json" \
  -d '{"password":"newpassword"}' \
  https://<SERVER_HOST>/api/accounts/<account_id>

HTTP response headers:

Status: 200 (OK)

HTTP response body:

{
  "updatedAt": 1430142736819
}

Delete an account

DELETE /api/accounts/<account_id>

curl

curl -X DELETE \
  -u username:password \
  http://<SERVER_HOST>/api/accounts/<account_id>

HTTP response headers:

Status: 200 (OK)

HTTP response body:

{}

Requesting A Password Reset

POST /api/requestPasswordReset

curl

curl -X POST \
  -u username:password \
  -d '{"email":"[email protected]"}' \
  http://<SERVER_HOST>/api/requestPasswordReset

HTTP response headers:

Status: 200 (OK)

HTTP response body:

{}

Also, backwards compatibility is an issue, since people have not supplied emails earlier

Status API

DiMe event count DiMe document count DiMe status, active loggers, API activity (log)