diff --git a/fern/docs.yml b/fern/docs.yml index 48e046e..845d8d0 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -10,8 +10,15 @@ navigation: path: ./docs/pages/overview.mdx - page: Authentication path: ./docs/pages/authentication.mdx + - page: Querying with OData + path: ./docs/pages/querying.mdx - page: Software Developement Kits path: ./docs/pages/sdks.mdx + - page: FAQ + path: ./docs/pages/faq.mdx + - page: Terms of use + path: ./docs/pages/terms.mdx + - api: API Reference api-name: api snippets: @@ -31,9 +38,11 @@ navbar-links: colors: accentPrimary: dark: "#b3f606" - light: "#456003" + light: "#608502" logo: dark: ./docs/assets/projectmanager_logo_white.png light: ./docs/assets/projectmanager_logo_black.png height: 30 + +favicon: projectmanager_favicon.png \ No newline at end of file diff --git a/fern/docs/assets/projectmanager_favicon.png b/fern/docs/assets/projectmanager_favicon.png new file mode 100644 index 0000000..b3f9cfd Binary files /dev/null and b/fern/docs/assets/projectmanager_favicon.png differ diff --git a/fern/docs/pages/authentication.mdx b/fern/docs/pages/authentication.mdx index e69de29..7ec5ea0 100644 --- a/fern/docs/pages/authentication.mdx +++ b/fern/docs/pages/authentication.mdx @@ -0,0 +1,68 @@ +The ProjectManager REST API v4 uses API keys generated from within the ProjectManager application. + +Credentials are sent to the API using the Authorization header as follows: + +```bash +Authorization: Bearer +``` + +## Generating an API key + +To create an API key to begin using the ProjectManager v4 API, follow these steps: + +1. Log onto your ProjectManager workspace. Note that each API key is tied to a workspace. +2. Click on your name in the bottom left hand corner of the screen, then select "Account". If you cannot see this option, check with your account representative to verify that you have been granted access to the REST API v4. + +![Account](https://files.readme.io/0a37a73-image.png) + +3. On the "Account" popup, select the "API" tab on the left hand side. + +![API](https://files.readme.io/ab2bcfd-image.png) + +4. Select the API V4 section and click "Create API Key". + +![API Key](https://files.readme.io/f55034b-image.png) + +5. Give your API key a name that you can use to remember it. When you click "Generate Tokens", you MUST copy and save your API key. Once generated, the API key can never be viewed again. + +6. We recommend rotating your API keys regularly to ensure that none are leaked or accidentally shared outside your organization. You can use the API key screen to maintain and revoke old tokens and create new ones. + +![Revoke](https://files.readme.io/5f30720-image.png) + +## Using the SDK to authenticate + +If you use a ProjectManager SDK, provide your token credentials using the `WithBearerToken` method as follows: + + + + ```csharp + return ProjectManagerClient + .WithCustomEnvironment(env) + .WithBearerToken(apiKey); + ``` + + + ```python + client = ProjectManagerClient() + client = client.with_custom_environment(env) + client = client.with_bearer_token(api_key) + ``` + + + ```go + client := NewProjectManagerClient() + client.WithCustomEnvironment(env) + client.WithBearerToken(apiKey) + ``` + + + ```java + ProjectManagerClient client = new ProjectManagerClient() + .withCustomEnvironment(env) + .withBearerToken(apiKey); + ``` + + + +The value provided to `WithCustomEnvironment` should be `api.projectmanager.com`. +The value provided to `WithBearerToken` should be the API key you generated. \ No newline at end of file diff --git a/fern/docs/pages/faq.mdx b/fern/docs/pages/faq.mdx index e69de29..9e6be64 100644 --- a/fern/docs/pages/faq.mdx +++ b/fern/docs/pages/faq.mdx @@ -0,0 +1,32 @@ +## Why does the API have different models for Create and Retrieve? + +The ProjectManager API v4 provides customized data models for each type of API. This allows the API to expose only the fields that are relevant for each specific action. + +As an example, some fields like `ShortCode` are assigned by the ProjectManager system. These fields are not available on the Create or Update models, but they appear on the Retrieve and Query models. + +## I'm using an older version of the API - how can I upgrade to v4? + +The new REST API v4 provides much more functionality than the older V1 and V3 APIs. ProjectManager encourages everyone to upgrade as soon as possible. + +Here's how to upgrade. + +#### API v3 Customers + +If you're on the API v3, you can start using API v4 calls right away. Just visit the ProjectManager v4 API keys page to learn how to create an API key for v4. +Once you have an API key for v4, you can begin using one of ProjectManager's available software development kits or begin writing your own code by viewing API documentation online. + +#### API v1 Customers + +Developers using the V1 API must schedule an upgrade for their account before they can begin using API v4. Contact your support representative today to schedule an upgrade at [support@projectmanager.com](mailto:support@projectmanager.com). + +## How can I check on the status of the ProjectManager API? + +The ProjectManager team monitors status of the application and API on https://status.projectmanager.com/ - you can visit this site and bookmark it to be notified whenever an incident occurs that affects the usability of the API. + +## How do I know if ProjectManager is secure? + +ProjectManager maintains information about its security certifications and policies on https://trust.projectmanager.com/ - customers can visit this site to request access to security certification documentation. + +## How can I get support as a developer? + +If you need assistance with the ProjectManager application, please contact support@projectmanager.com via email. diff --git a/fern/docs/pages/overview.mdx b/fern/docs/pages/overview.mdx index acd69e0..3ca37cc 100644 --- a/fern/docs/pages/overview.mdx +++ b/fern/docs/pages/overview.mdx @@ -1,4 +1,6 @@ + REST API v4 is the newest iteration of our application programming interface for ProjectManager.com. + ## Quickstart diff --git a/fern/docs/pages/querying.mdx b/fern/docs/pages/querying.mdx index e69de29..b620d0d 100644 --- a/fern/docs/pages/querying.mdx +++ b/fern/docs/pages/querying.mdx @@ -0,0 +1,57 @@ +When you use the ProjectManager v4 API, you can search for your information using the query language [OData](https://www.odata.org/). All data types within ProjectManager can be retrieved using OData queries. + +So let's break this down - what is an OData query? It is a type of query that allows you to: + +- **Filter** records based on criteria you specify in the `$filter` parameter. +- **Paginate** your results using `$top` and `$skip`. +- **Sort** your query results using `$orderby`. +- **Fetch** additional data using `$expand`. +- **Reduce** unwanted data using `$select`. + +Let's walk through the basics for an OData query. + +## Filtering records using OData + +Whenever you want to find a specific record in the ProjectManager system, you can use an OData filter statement to search. Microsoft provides a nice tutorial page on [learning OData filter expressions](https://learn.microsoft.com/en-us/dynamics-nav/using-filter-expressions-in-odata-uris) which goes into more detail, but let's summarize it here. + +- Search for projects with a specific where a field value matches using an `$filter={field-name} eq {value}` statement, like `$filter=shortCode eq MyNewProject` +- Search for tasks more recent than a specific time using an `$filter={field-name} gt {date}` statement, like `$filter=createDate gt 2023-03-01` +- Search for a resource with a comment in its "notes" field using an `$filter=substringof({field-name}, '{substring}')` statement, like `$filter=substringof(notes, 'test')`. + +There are lots of comparators and functions within OData filtering that you may want to learn. + +| Name | Example | +|----------------------|----------------------------------| +| Equals | `{field} eq {value}` | +| Greater Than | `{field} gt {value}` | +| Greater Than Or Equal| `{field} ge {value}` | +| Less Than | `{field} lt {value}` | +| Less Than Or Equal | `{field} le {value}` | +| Not Equal | `{field} ne {value}` | +| Contains | `substringof({field}, {value})` | +| Starts With | `startswith({field}, {value})` | +| Ends With | `endswith({field}, {value})` | + +When specifying values in your query, keep in mind these things: + +- Numeric values are presented as-is, for example `count eq 7` +- String values are enclosed in single quotes, for example `name eq 'Bob Smith'` +- Date values are always written in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format, also known as YYYY-MM-DD. For example, `createDate gt 2023-01-01` + +Got questions about OData queries? Visit our [ProjectManager developer discussion boards](https://developer.projectmanager.com/discuss) and compare notes with other developers! + +## Pagination using OData + +The standard for OData pagination uses the concept of **top** and **skip**. Here's how it works. + +1. The server begins to produce a list of all records matching your $filter statement in the order specified by the $orderby parameter. + +2. The server will omit the number of records specified by the $skip parameter, if it is present. + +3. If there are still more records remaining after the $skip parameter has been exhausted, the server will begin delivering records up until the $top value is reached. + +This allows you to paginate records easily. If you want to retrieve the top 50 records in a table, you specify `$top=50`. To retrieve the second page of results, specify `$skip=50` and `$top=50`. + +## Expanding data + +Some OData query endpoints allow you to fetch additional data using the `$expand` parameter. The documentation for the API will explain what options are available and how to use them on each endpoint. \ No newline at end of file diff --git a/fern/docs/pages/terms.mdx b/fern/docs/pages/terms.mdx index e69de29..16db9d8 100644 --- a/fern/docs/pages/terms.mdx +++ b/fern/docs/pages/terms.mdx @@ -0,0 +1,6 @@ +You can view ProjectManager's terms of use and privacy policy online using these links. + +- [ProjectManager.com terms of use](https://www.projectmanager.com/terms) +- [ProjectManager.com privacy policy](https://www.projectmanager.com/privacy) +- [ProjectManager.com trust and security](https://trust.projectmanager.com/) +- [ProjectManager.com site and API status](https://status.projectmanager.com/) \ No newline at end of file