chore: copy edits (#44)

Co-authored-by: Marcin Rataj <lidel@lidel.org>
ipfs · Jul 30, 2020 · 5976663 · 5976663
1 parent 3f981ff
commit 5976663
Show file tree

Hide file tree

Showing 2 changed files with 63 additions and 66 deletions.
diff --git a/README.md b/README.md
@@ -14,31 +14,31 @@
 
 ## About
 
-A Pinning Service is a service that accepts [CIDs](https://github.com/ipld/cid/) from a user and will host the data associated with them.
+A **pinning service** is a service that accepts [CIDs](https://github.com/ipld/cid/) from a user in order to host the data associated with them.
 
-The rationale behind defining a generic pinning service API is to have a baseline functionality and interface that can be provided by these services so that tools can be built on top of a common base of functionality. 
+The rationale behind defining a generic pinning service API is to have a baseline functionality and interface that can be provided by pinning services, so that tools can be built on top of a common base of functionality. 
 
-In [this presentation](https://youtu.be/Pcv8Bt4HMVU), IPFS creator Juan Benet discusses current and potential pinning use cases and how a standardized IPFS Pinning API could meet these envisioned needs. 
+In [this presentation](https://youtu.be/Pcv8Bt4HMVU), IPFS creator Juan Benet discusses current and potential pinning use cases, and how a standardized IPFS pinning API can meet these envisioned needs. 
 
 The API spec in this repo is the first step towards that future.
 
 ## Specification 
 
-API is defined as OpenAPI spec in YAML format:
+This API is defined as an OpenAPI spec in YAML format:
 
 * **[ipfs-pinning-service.yaml](./ipfs-pinning-service.yaml)**
 
 
 ### Documentation
 
-API documentation generated from the YAML file can be found at:
+You can find human-readable API documentation generated from the YAML file here:
 
 - **[https://ipfs.github.io/pinning-services-api-spec](https://ipfs.github.io/pinning-services-api-spec/)**
 
 ## Adoption
 
-We are working with pinning services to expose this API, stay tunned  ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
-  - `{this could be your project}`
+We are currently working with pinning services to expose this API — so stay tuned!  ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
+  - `{your project could go here}`
 
 Built-in support for pinning services exposing this API is coming to IPFS tooling in Q3: 
   - [go-ipfs](https://github.com/ipfs/go-ipfs) / [js-ipfs](https://github.com/ipfs/js-ipfs) (CLI/HTTP API)  ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square)
@@ -48,29 +48,30 @@ Built-in support for pinning services exposing this API is coming to IPFS toolin
 ### Timeline
 
 - 2019 Q2 
-  - Creation of a generic Pinning Service API proposed in [ipfs/notes/issues/378](https://github.com/ipfs/notes/issues/378)
+  - Creation of a generic pinning service API proposed in [ipfs/notes/issues/378](https://github.com/ipfs/notes/issues/378)
 - 2020 Q2
   - Pinning Summit 2020 ([website](https://ipfspinningsummit.com/), [recorded talks](https://www.youtube.com/watch?v=rYD2lfuatJM&list=PLuhRWgmPaHtTvsxuZ9T-tMlu_v0lja6v5))
 - 2020 Q3
-  - IPFS GUI Team looking into adding support for Pinning Services into Desktop apps
+  - IPFS GUI WG working on adding support for pinning services into IPFS Desktop/Web UI:
     - [Epic: Pinning service integration · Issue #91 · ipfs/ipfs-gui](https://github.com/ipfs/ipfs-gui/issues/91)
-    - [Analysis of Remote Pinning Services vs the needs of IPFS WebUI](https://docs.google.com/document/d/1f0R7woLtW_YTv9P9IOrUNK6QafgctJ7qTggEUdepD_c/)
+    - [Analysis of remote pinning services vs the needs of IPFS Web UI](https://docs.google.com/document/d/1f0R7woLtW_YTv9P9IOrUNK6QafgctJ7qTggEUdepD_c/)
   - [ipfs/pinning-services-api-specs](https://github.com/ipfs/pinning-services-api-specs) is created as a place for stakeholders to collaborate and finalize the API
-    - 2020-07-14: spec in draft status is ready for implementation
+    - 2020-07-14: Spec in draft status is ready for implementation
 
 
 ## Contribute
 
-Suggestions, contributions, criticisms are welcome. Though please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows.
+Suggestions, contributions, and criticisms are welcome! However, please make sure to familiarize yourself deeply with IPFS, the models it adopts, and the principles it follows.
+
 This repository falls under the IPFS [Code of Conduct](https://github.com/ipfs/community/blob/master/code-of-conduct.md).
 
 ### Spec lifecycle
 
-We use the following label system to identify the state of this spec:
+We use the following label system to identify the state of aspects of this spec:
 
-- ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) - A work-in-progress, possibly to describe an idea before actually committing to a full draft of the spec.
-- ![](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) - A draft that is ready to review. It should be implementable.
-- ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) - A spec that has been adopted (implemented) and can be used as a reference point to learn how the system works.
-- ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) - We consider this spec to close to final, it might be improved but the system it specifies should not change fundamentally.
-- ![](https://img.shields.io/badge/status-permanent-blue.svg?style=flat-square) - This spec will not change.
-- ![](https://img.shields.io/badge/status-deprecated-red.svg?style=flat-square) - This spec is no longer in use.
+- ![](https://img.shields.io/badge/status-wip-orange.svg?style=flat-square) — A work-in-progress, possibly to describe an idea before actually committing to a full draft of the spec
+- ![](https://img.shields.io/badge/status-draft-yellow.svg?style=flat-square) — A draft that is ready to review, and should be implementable
+- ![](https://img.shields.io/badge/status-reliable-green.svg?style=flat-square) — A spec that has been adopted (implemented) and can be used as a reference to learn how the system works
+- ![](https://img.shields.io/badge/status-stable-brightgreen.svg?style=flat-square) — We consider this spec to close to final; it might be improved, but the system it specifies should not fundamentally change
+- ![](https://img.shields.io/badge/status-permanent-blue.svg?style=flat-square) — This spec will not change
+- ![](https://img.shields.io/badge/status-deprecated-red.svg?style=flat-square) — This spec is no longer in use
diff --git a/ipfs-pinning-service.yaml b/ipfs-pinning-service.yaml
@@ -16,19 +16,15 @@ The IPFS Pinning Service API is intended to be an implementation-agnostic API&#x
 - For use in client mode by IPFS nodes and GUI-based applications
 
 
-> **Note**: while ready for implementation, this spec is still a work in progress! 🏗️
-
-> **Your input and feedback are welcome and valuable as we develop this API spec.
-
-> Please join the design discussion at [github.com/ipfs/pinning-services-api-spec](https://github.com/ipfs/pinning-services-api-spec).**
+> **Note**: while ready for implementation, this spec is still a work in progress! 🏗️  **Your input and feedback are welcome and valuable as we develop this API spec. Please join the design discussion at [github.com/ipfs/pinning-services-api-spec](https://github.com/ipfs/pinning-services-api-spec).**
 
 
 # Schemas
 
 This section describes the most important object types and conventions.
 
 
-A full list of fields and schemas can be found in the `schemas` section of the YAML file.
+A full list of fields and schemas can be found in the `schemas` section of the [YAML file](https://github.com/ipfs/pinning-services-api-spec/blob/master/ipfs-pinning-service.yaml).
 
 ## Objects
 
@@ -37,22 +33,22 @@ A full list of fields and schemas can be found in the `schemas` section of the Y
 The `Pin` object is a representation of a pin request.
 
 
-It includes the `cid` of data to be pinned and optional metadata in `providers` and `meta`.
+It includes the `cid` of data to be pinned, as well as optional metadata in `providers` and `meta`.
 
 
 ### Pin status object
 
 The `PinStatus` object is a representation of a pinning operation.
 
-It includes the original `pin` object, along with current `status` and `id`, which which can be used for status checks and management.
+It includes the original `pin` object, along with current `status` and `id`, which can be used for status checks and management.
 
 
 ## The pin lifecycle
 
 
 ### Creating a new pin object
 
-The user sends one or more `Pin` objects via `POST /pins` and receives `PinStatus` response for each:
+The user sends one or more `Pin` objects via `POST /pins` and receives a `PinStatus` response for each:
 
 - `id` in `PinStatus` is `cid-of-pin-object`, which can can be used for checking status, modifying the pin, and/or removing the pin in the future
 
@@ -81,28 +77,28 @@ A pin object can be removed via `DELETE /pins/{cid-of-pin-object}`.
 ## Provider hints
 
 Pinning of new data can be accelerated by providing a list of known data
-sources in `Pin.providers` and connecting at least one of them to pinning
+sources in `Pin.providers`, and connecting at least one of them to pinning
 service nodes at `PinStatus.providers`.
 
 
-The most common scenario is a client putting own IPFS node's multiaddrs in
-`Pin.providers`  and then directly connecting to every multiaddr returned by
-Pinning Service in `PinStatus.providers` to initiate transfer.
+The most common scenario is a client putting its own IPFS node's multiaddrs in
+`Pin.providers`,  and then directly connecting to every multiaddr returned by
+a pinning service in `PinStatus.providers` to initiate transfer.
 
 
 This ensures data transfer starts immediately (without waiting for provider
-discovery over DHT) and direct dial from a client works around peer routing
-issues in restrictive network topologies such as NAT.
+discovery over DHT), and direct dial from a client works around peer routing
+issues in restrictive network topologies such as NATs.
 
 
 ## Custom metadata
 
-Pinning services are encouraged to add support for additional features by leveraging the following optional `meta` attributes. Note that it is OK to ommit or ignore `meta` attributes; doing so should not impact the basic pinning functionality.
+Pinning services are encouraged to add support for additional features by leveraging the following optional `meta` attributes. Note that it is OK to omit or ignore `meta` attributes; doing so should not impact the basic pinning functionality.
 
 
 - `Pin.meta[app_id]`: Attaching a unique identifier to pins created by an app enables filtering pins per app via `?meta={\"app_id\":<UUID>}`
 
-- `PinStatus.meta[status_details]`: Service-specific details. For example, when `PinStatus.status=failed` it could provide a reason why a pin operation failed (e.g. lack of funds, DAG too big, etc.)
+- `PinStatus.meta[status_details]`: Service-specific details. For example, when `PinStatus.status=failed`, it could provide a reason why a pin operation failed (e.g. lack of funds, DAG too big, etc.)
 
 
 While these attributes can be vendor-specific, we encourage the community at large to leverage these `meta` attributes as a sandbox to come up with conventions that could become part of future revisions of this API.
@@ -113,10 +109,10 @@ While these attributes can be vendor-specific, we encourage the community at lar
 Pin objects can be listed by executing `GET /pins` with optional parameters:
 
 
-- When no filters are provided, the endpoint will return a small batch of 10 most
+- When no filters are provided, the endpoint will return a small batch of the 10 most
   recently created items, from the latest to the oldest.
 
-- The number of returned items can be adjusted with `limit` parameter
+- The number of returned items can be adjusted with the `limit` parameter
   (implicit default is 10).
 
 - If the value in `PinResults.count` is bigger than the length of
@@ -127,7 +123,7 @@ Pin objects can be listed by executing `GET /pins` with optional parameters:
   Repeat to read all results.
 
 - Returned results can be fine-tuned by applying optional `after`, `cid`,
-  `status` or `meta` filters.
+  `status`, or `meta` filters.
 
 
 > **Note**: pagination by the `created` timestamp requires each value to be
@@ -144,7 +140,7 @@ paths:
   /pins:
     get:
       summary: List pin objects
-      description: List all the pin objects, matching optional filters. When no filter is provided, only successfull pins are returned.
+      description: List all the pin objects, matching optional filters; when no filter is provided, only successful pins are returned
       tags:
         - pins
       parameters:
@@ -167,7 +163,7 @@ paths:
           $ref: '#/components/responses/InternalServerError'
     post:
       summary: Add pin object
-      description: Add a new pin object for the current access token.
+      description: Add a new pin object for the current access token
       tags:
         - pins
       requestBody:
@@ -203,7 +199,7 @@ paths:
           type: string
     get:
       summary: Get pin object
-      description: Get a pin object and its status.
+      description: Get a pin object and its status
       tags:
         - pins
       responses:
@@ -221,7 +217,7 @@ paths:
           $ref: '#/components/responses/InternalServerError'
     post:
       summary: Modify pin object
-      description: Modify an existing pin object.
+      description: Modify an existing pin object
       tags:
         - pins
       requestBody:
@@ -251,7 +247,7 @@ paths:
           $ref: '#/components/responses/InternalServerError'
     delete:
       summary: Remove pin object
-      description: Remove a pin object.
+      description: Remove a pin object
       tags:
         - pins
       responses:
@@ -270,7 +266,7 @@ components:
   schemas:
 
     PinResults:
-      description: Response used for listing Pin objects matching request
+      description: Response used for listing pin objects matching request
       type: object
       required:
         - count
@@ -291,7 +287,7 @@ components:
           maxItems: 1000
 
     PinStatus:
-      description: pin object with status
+      description: Pin object with status
       type: object
       required:
         - id
@@ -307,7 +303,7 @@ components:
         status:
           $ref: '#/components/schemas/Status'
         created:
-          description: immutable timestamp; indicates when pin request entered pinning service; can be used for filtering results and pagination
+          description: Immutable timestamp indicating when a pin request entered a pinning service; can be used for filtering results and pagination
           type: string
           format: date-time  # RFC 3339, section 5.6
           example: "2020-07-27T17:32:28Z"
@@ -319,7 +315,7 @@ components:
           $ref: '#/components/schemas/StatusMeta'
 
     Pin:
-      description: pin object
+      description: Pin object
       type: object
       required:
         - cid
@@ -334,16 +330,16 @@ components:
           $ref: '#/components/schemas/PinMeta'
 
     Status:
-      description: status a pin object can have at a pinning service
+      description: Status a pin object can have at a pinning service
       type: string
       enum:
-        - queued     # pinning operation is waiting in the queue, additional info can be returned in meta[status_details]      
-        - pinning    # pinning in progress, additional info can be returned in meta[status_details]
+        - queued     # pinning operation is waiting in the queue; additional info can be returned in meta[status_details]      
+        - pinning    # pinning in progress; additional info can be returned in meta[status_details]
         - pinned     # pinned successfully
-        - failed     # pining service was unable to finish pinning operation, additional info can be found in meta[status_details]
+        - failed     # pinning service was unable to finish pinning operation; additional info can be found in meta[status_details]
 
     ServiceProviders:
-      description: list of multiaddrs designated by pinning service for transferring any new data from external peers
+      description: List of multiaddrs designated by pinning service for transferring any new data from external peers
       type: array
       items:
         type: string
@@ -353,7 +349,7 @@ components:
       example: ['/dnsaddr/pin-service.example.com']
 
     DataProviders:
-      description: optional list of multiaddrs known to provide the data
+      description: Optional list of multiaddrs known to provide the data
       type: array
       items:
         type: string
@@ -363,7 +359,7 @@ components:
       example: ['/p2p/QmSourcePeerId']
 
     PinMeta:
-      description: optional metadata for pin object
+      description: Optional metadata for pin object
       type: object
       additionalProperties:
         type: string
@@ -373,7 +369,7 @@ components:
         app_id: "99986338-1113-4706-8302-4420da6158aa" # Pin.meta[app_id], useful for filtering pins per app
 
     StatusMeta:
-      description: optional metadata for PinStatus response
+      description: Optional metadata for PinStatus response
       type: object
       additionalProperties:
         type: string
@@ -383,7 +379,7 @@ components:
         status_details: "Fetching new data: 50% complete" # PinStatus.meta[status_details], when status=pinning
 
     Error:
-      description: base error object
+      description: Base error object
       type: object
       required:
         - code
@@ -397,7 +393,7 @@ components:
   parameters:
 
     before:
-      description: return results created (queued) before provided timestamp
+      description: Return results created (queued) before provided timestamp
       name: before
       in: query
       required: false
@@ -407,7 +403,7 @@ components:
       example: "2020-07-27T17:32:28Z"
 
     after:
-      description: return results created (queued) after provided timestamp
+      description: Return results created (queued) after provided timestamp
       name: after
       in: query
       required: false
@@ -417,7 +413,7 @@ components:
       example: "2020-07-27T17:32:28Z"
 
     limit:
-      description: max records to return
+      description: Max records to return
       name: limit
       in: query
       required: false
@@ -429,7 +425,7 @@ components:
         default: 10
 
     cid:
-      description: return pin objects for the specified CID(s)
+      description: Return pin objects for the specified CID(s)
       name: cid
       in: query
       required: false
@@ -444,14 +440,14 @@ components:
       explode: false
       examples:
         oneId:
-          summary: example of a single CID
+          summary: Example of a single CID
           value: [QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR]   # ?cid=Qm
         multipleIds:
-          summary: example of multiple CIDs
+          summary: Example of multiple CIDs
           value: [QmbWqxBEKC3P8tqsKc98xmWNzrzDtRLMiMPL8wBuTGsMnR,bafkreigtdgsgv2f3bkhsmxvku3bpnnqzubcxeupf7fff5f7l7tlm2v237a]   # ?cid=Qm,bafy
 
     status:
-      description: return pin objects for pins with the specified status
+      description: Return pin objects for pins with the specified status
       name: status
       in: query
       required: false
@@ -465,7 +461,7 @@ components:
       explode: false
 
     meta:
-      description: return pin objects that match specified metadata
+      description: Return pin objects that match specified metadata
       name: meta
       in: query
       required: false
@@ -513,7 +509,7 @@ components:
   securitySchemes:
     accessToken:
       description: "
-An opaque token is required to be sent with each request in HTTP header:
+An opaque token is required to be sent with each request in the HTTP header:
 
 - `Authorization: Bearer <access-token>`