update documentations

Financial-Times · Oct 31, 2019 · fa39a18 · fa39a18
1 parent 9c30dc1
commit fa39a18
Show file tree

Hide file tree

Showing 2 changed files with 66 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -11,11 +11,9 @@ Draft Annotations API is a microservice that provides access to draft annotation
 Download the source code, dependencies and test dependencies:
 
 ```
-mkdir $GOPATH/src/github.com/Financial-Times/draft-annotations-api
-cd $GOPATH/src/github.com/Financial-Times
 git clone https://github.com/Financial-Times/draft-annotations-api.git
 cd draft-annotations-api
-GO111MODULE=on go build -mod=readonly
+go build -mod=readonly
 ```
 
 ## Running locally
@@ -51,11 +49,11 @@ Options:
 
     1. Either using curl:
 
-            curl http://localhost:8080/draft/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations | json_pp
+            curl http://localhost:8080/drafts/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations | json_pp
 
     1. Or using [httpie](https://github.com/jkbrzt/httpie):
 
-            http GET http://localhost:8080/draft/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations
+            http GET http://localhost:8080/drafts/content/b7b871f6-8a89-11e4-8e24-00144feabdc0/annotations
 
 ## Build and deployment
 
@@ -73,7 +71,7 @@ For a full description of API endpoints for the service, please see the [Open AP
 Using curl:
 
 ```
-curl http://localhost:8080/draft/content/{content-uuid}/annotations | jq
+curl http://localhost:8080/drafts/content/{content-uuid}/annotations | jq
 ```
 
 A GET request on this endpoint fetches the draft annotations for a specific piece of content by calling
@@ -121,7 +119,7 @@ This is an example response body:
 Using curl:
 
 ```
-curl http://localhost:8080/draft/content/{content-uuid}/annotations -X POST --data '{
+curl http://localhost:8080/drafts/content/{content-uuid}/annotations -X POST --data '{
           "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd"
           "predicate": "http://www.ft.com/ontology/annotation/about",
 }'
@@ -214,7 +212,7 @@ The listings below shows an example of a canonicalized response.
 Using curl:
 
 ```
-curl http://localhost:8080/draft/content/{content-uuid}/annotations/{concept-uuid} | jq
+curl http://localhost:8080/drafts/content/{content-uuid}/annotations/{concept-uuid} | jq
 ```
 
 A DELETE request on this endpoint deletes all the annotations for a single concept from the editorially curated published annotations for a specific piece of content. To retrieve these specific annotations it calls [UPP Public Annotations API](https://github.com/Financial-Times/public-annotations-api) using the "lifecycle" parameter.
@@ -245,7 +243,7 @@ This is an example response body:
 Using curl:
 
 ```
-curl http://localhost:8080/draft/content/{content-uuid}/annotations/{concept-uuid} -X PATCH --data '{
+curl http://localhost:8080/drafts/content/{content-uuid}/annotations/{concept-uuid} -X PATCH --data '{
         "id": "http://www.ft.com/thing/d7de27f8-1633-3fcc-b308-c95a2ad7d1cd"
 }'
 ```

diff --git a/_ft/api.yml b/_ft/api.yml
@@ -87,6 +87,7 @@ paths:
                         - http://www.ft.com/ontology/annotation/mentions
                         - http://www.ft.com/ontology/classification/isClassifiedBy
                         - http://www.ft.com/ontology/implicitlyClassifiedBy
+                        - http://www.ft.com/ontology/hasBrand
                     type:
                       type: string
                       description: The type of concept, i.e. Person, Organisation, Topic
@@ -169,7 +170,7 @@ paths:
           description: The content with the specified UUID was not found.
         500:
           description: Internal server error
-  /drafts/content/{uuid}/annotations/{conceptUuid}:
+  /drafts/content/{uuid}/annotations/{conceptUUID}:
     delete:
       summary: Delete all annotations with a given concept from the draft annotations for a specified content
       description: Returns the draft annotations for the content after the delete operation.
@@ -184,7 +185,7 @@ paths:
           required: true
           type: string
           x-example: 8df16ae8-0dfd-4859-a5ff-eeb9644bed35
-        - name: conceptUuid
+        - name: conceptUUID
           in: path
           description: The UUID of the concept to be deleted
           required: true
@@ -204,6 +205,62 @@ paths:
           description: Content with the specified UUID was not found
         500:
           description: Internal server error
+    patch:
+      summary: Replace all annotations with given conceptUUID from the draft annotations for a specified content with new annotation provided in the body
+      description: Returns the draft annotations for the content after the replace operation.
+      tags:
+        - Public API
+      consumes:
+        - application/json
+      produces:
+        - application/json
+      parameters:
+        - name: uuid
+          in: path
+          description: The UUID of the content
+          required: true
+          type: string
+          x-example: 8df16ae8-0dfd-4859-a5ff-eeb9644bed35
+        - name: conceptUUID
+          in: path
+          description: The UUID of the concept to be replaced
+          required: true
+          type: string
+          x-example: ababe00a-d732-4690-b283-585e7f264d2f
+        - name: body
+          in: body
+          description: An annotation for specific content
+          required: true
+          schema: 
+            type: object
+            properties:
+              id:
+                type: string
+                description: The UUID of the new concept
+                x-example: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
+              predicate:
+                type: string
+                description: The relationship between the concept and this piece of FT content
+                x-example: http://www.ft.com/ontology/annotation/mentions
+            example:
+              id: http://www.ft.com/thing/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
+              predicate: http://www.ft.com/ontology/annotation/mentions
+            required:
+              - id
+      responses:
+        200:
+          description: Returns the canonicalized array of annotations that have been successfully saved in PAC.
+          examples:
+            application/json:
+              annotations:
+                - id: http://api.ft.com/things/d7113d1d-ed66-3adf-9910-1f62b2c40e6a
+                  predicate: http://www.ft.com/ontology/annotation/mentions
+        400:
+          description: Invalid content or concept UUID supplied
+        404:
+          description: Content with the specified UUID was not found
+        500:
+          description: Internal server error
   /__health:
     get:
       summary: Healthchecks