Skip to content

Commit 7d88e2f

Browse files
sanscontextsanscontext
authored
Merge pull request #6 from segmentio/add-dirs
Add dirs
2 parents 668c9d6 + c8cd66e commit 7d88e2f

File tree

1,228 files changed

+65510
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,228 files changed

+65510
-3
lines changed

‎api/config-api/api-design.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: API Design
3+
---
4+
5+
## API Evolution: Versioning and Compatibility
6+
7+
Segment strives to maintain a strict contract around the stability of our APIs once they reach maturity.
8+
9+
The Config API is versioned statically by path prefix. The current version, `/v1beta`, is stable and suitable for production use, but not 100% mature. We will not ship any backwards incompatible breaking changes after its public launch on December 12, 2018. However, we may release new versions of the API as further `/v1betaX` releases or as major version releases (such as `/v1`).
10+
11+
The reason the path is currently `/v1beta` is to signify both that Segment's product model is evolving and that we are looking for feedback from developers on how best to expose that model for public consumption, extension, and automation.
12+
13+
Therefore, `/v1beta` is subject to deprecation with 3 months of written notice after the release of `/v1`, should we decide to land any breaking changes in the final `/v1` release.
14+
15+
We're always actively seeking feedback on the ergonomics and breadth of our APIs. If you have ideas of how we can improve them that you'd like to see as extensions to `/v1beta` or considered for changes in `/v1`, please don't hesitate to [get in touch](https://segment.com/help/contact/).
16+
17+
## Common Methods and Fields
18+
19+
The Config API is a set of REST APIs for managing Segment resources. The primary Segment resources are:
20+
21+
* Personal Access Tokens
22+
* Workspaces
23+
* Sources
24+
* Destinations
25+
* Tracking Plans
26+
27+
You can manage each resource using standard methods:
28+
29+
| Method | HTTP Mapping |
30+
|--------|-----------------------|
31+
| List | GET <collection URL> |
32+
| Get | GET <resource URL> |
33+
| Create | POST <collection URL> |
34+
| Update | PATCH <resource URL> |
35+
| Delete | DELETE <resource URL> |
36+
37+
## Errors
38+
39+
| Error | HTTP Status | Code | Reasons |
40+
|--------------------|---------------------------|------|-------------------------------------------------------------------------------------------------------|
41+
| Invalid Argument | 400 Bad Request | 3 | The request contains invalid JSON or a field contains an invalid value |
42+
| Unauthenticated | 401 Unauthorized | 16 | The access token is missing or invalid |
43+
| PermissionDenied | 403 Forbidden | 7 | An access token with `write` scope is required for the Create, Update and Delete methods |
44+
| Not Found | 404 Not Found | 5 | The request or resource could not be found. Either the request method or path is incorrect, or the resource does not exist in this workspace (sometimes because of a typo). |
45+
| Already Exists | 409 Conflict | 6 | A resource (e.g. source) already exists with the given name |
46+
| Resource Exhausted | 429 Too Many Requests | 8 | The 60 req / sec rate limit was exhausted |
47+
| Internal | 500 Internal Server Error | 13 | Segment encountered an error processing the request |
48+
| Unimplemented | 501 Not Implemented | 12 | The method is not supported or implemented |
49+
| Unavailable | 503 Service Unavailable | 14 | The API is down |
50+
| upstream connect error <br /> or disconnect/reset before headers | 503 Service Unavailable | n/a | The URL is invalid so the requesst can't route to an upstream API service |
51+
52+
## Pagination
53+
54+
The List method is paginated. Requests take an optional `page_size` parameter which generally defaults to 10 or 100 items. If there are more than `page_size` items in a collection, the response includes a `next_page_token` field. You can then supply this as `page_token` parameter to the next List request. If there are no more items in the collection, `next_page_token` will be empty.
55+
56+
## Update Mask
57+
58+
Update methods follow PATCH semantics. In addition to the data to update, the method requires an explicit set of field names to update. This removes all ambiguity around empty values.
59+
60+
```shell
61+
$ curl -X PATCH \
62+
-h "Authorization: Bearer $ACCESS_TOKEN" \
63+
-d '{
64+
"destination": {
65+
"enabled": true,
66+
"update_mask": {
67+
"paths": [
68+
"destination.enabled"
69+
]
70+
}
71+
}'
72+
'https://platform.segmentapis.com/v1beta/workspaces/myworkspace/sources/js/destinations/google-analytics'
73+
```
74+
75+
Note that specifying an update path with no value will change the field to an empty value (e.g. "", 0, or false). For example this will result in `enabled` false:
76+
77+
```shell
78+
$ curl -X PATCH \
79+
-h "Authorization: Bearer $ACCESS_TOKEN" \
80+
-d '{
81+
"destination": {
82+
"update_mask": {
83+
"paths": [
84+
"destination.enabled"
85+
]
86+
}
87+
}'
88+
'https://platform.segmentapis.com/v1beta/workspaces/myworkspace/sources/js/destinations/google-analytics'
89+
```
90+
91+
And note that specifying data but no paths will not change the field value. For example this has no effect:
92+
93+
```shell
94+
$ curl -X PATCH \
95+
-h "Authorization: Bearer $ACCESS_TOKEN" \
96+
-d '{
97+
"destination": {
98+
"enabled": true
99+
}'
100+
'https://platform.segmentapis.com/v1beta/workspaces/myworkspace/sources/js/destinations/google-analytics'
101+
```
102+
103+
## Resource Names
104+
105+
Resources are named entities exposed by our services and APIs, and resource names are their identifiers. Each resource has its own unique resource name made up of the ID or slug of the resource itself and the IDs or slugs of any parent resources.
106+
107+
So a given Source resource might look like:
108+
109+
`workspaces/<customer-workspace-slug>/sources/<customer-source-slug>`
110+
111+
Segment APIs use scheme-less URIs for resource names. This allows us to generally follow REST URL conventions and provides a machine and human-legible standard for our identifiers.
112+
113+
Segment favors "slugs" over opaque IDs when the resource is customer- or Segment-named and unlikely to change, such as sources and destinations. For resources whose name is subject to change frequently, such as Tracking Plans, we will autogenerate prefixed IDs for you upon creation and use that in the fully qualified resource name.
114+
115+
While full resource names resemble normal URLs, they are not the same thing. A single resource may be exposed by different API versions, API protocols, or API network endpoints as Segment's APIs evolve.

‎api/config-api/authentication.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: Authentication
3+
---
4+
5+
You can access the Config API programmatically using access tokens. When you authenticate with an access token, you have access to any resource and permission assigned to the token.
6+
7+
## Create an Access Token
8+
9+
As a workspace owner, you can create access tokens via the Access Management page in Admin settings. You can assign the same granularity of permissions as you can for a logged-in user. As best practice, tokens should be assigned the least permissions needed to perform a required API action. All tokens are required to have a description.
10+
11+
> Warning: Secret Token
12+
>
13+
> Note that you can not retrieve the plain-text `token` later, so you should save it in a secret manager. If you lose the `token` you can generate a new one.
14+
15+
## Use a Access Token
16+
17+
Now that you have an access token, you can use this token to access the Config API by setting it in the `Authorization` header of your requests, for example:
18+
19+
```shell
20+
$ ACCESS_TOKEN=qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g
21+
22+
$ curl \
23+
-X GET \
24+
-H "Authorization: Bearer $ACCESS_TOKEN" \
25+
https://platform.segmentapis.com/v1beta/workspaces
26+
```
27+
28+
Example response:
29+
30+
```json
31+
{
32+
"workspaces": [
33+
{
34+
"name": "myworkspace",
35+
"display_name": "My Space",
36+
"id": "e5bdb0902b",
37+
"create_time": "2018-08-08T13:24:02.651Z"
38+
}
39+
]
40+
}
41+
```
42+
43+
## Scopes
44+
45+
You cannot use access tokens created with the `workspace:read` scope to create or update resources. If you do so, you'll get the following error:
46+
47+
```json
48+
{
49+
"error": "insufficient scope",
50+
"code": 7
51+
}
52+
```
53+
54+
See [Config API Errors](docs/config-api/api-design/#errors) for error codes.

‎api/config-api/destination-filters/fql.md

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: Filter Query Language
3+
hidden: true
4+
---
5+
6+
Filter Query Language ("FQL") is a simple language for filtering JSON objects
7+
used by the Transformations API to conditionally apply transformations. In the
8+
Transformations API, FQL statements evaluate to `true` or `false` based on the
9+
contents of each Segment event. If the statement evaluates to `true`, the
10+
transformation is applied, and if it is `false` the transformation is not applied.
11+
12+
In addition to boolean and equality operators like `and` and `>=`, FQL has
13+
built-in functions that make it more powerful such as `contains( str, substr )`
14+
and `match( str, pattern )`.
15+
16+
## Examples
17+
18+
Given the following JSON object:
19+
20+
```json
21+
{
22+
"event": "Button Clicked",
23+
"type": "track",
24+
"context": {
25+
"library": {
26+
"name": "analytics.js",
27+
"version": "1.0",
28+
}
29+
}
30+
}
31+
```
32+
33+
The following FQL statements will evaluate as follows:
34+
35+
| FQL | Result |
36+
| ---------------------------------------------------------------------- | ------- |
37+
| `event = 'Button Clicked'` | `true` |
38+
| `event = 'Screen Tapped'` | `false` |
39+
| `context.path.path = '/login'` | `false` |
40+
| `type = 'identify' or type = 'track'` | `true` |
41+
| `event = 'Button Clicked' and type = 'track'` | `true` |
42+
| `match( context.library.version, '1.*' )` | `true` |
43+
| `match( context.library.version, '2.*' )` | `false` |
44+
| `type = 'track' and ( event = 'Click' or match( event, 'Button *' ) )` | `true` |
45+
| `!contains( context.library.name, 'js' )` | `false` |
46+
47+
## Field Paths
48+
49+
FQL statements may refer to any field in the JSON object including top-level
50+
properties like `userId` or `event` as well as nested properties like
51+
`context.library.version` or `properties.title` using dot-separated paths. For
52+
example, the following fields can be pointed to by the associated field paths:
53+
54+
```
55+
{
56+
"type": "...", // type
57+
"event": "...", // event
58+
"context": { // context
59+
"library": { // context.library
60+
"name": "..." // context.library.name
61+
},
62+
"page": { // context. page
63+
"path": "...", // context.page.path
64+
}
65+
}
66+
}
67+
```
68+
69+
## Operators
70+
71+
### Boolean
72+
73+
| Operator | Left Side | Right Side | Result |
74+
| -------- | ---------------- | ---------------- | ----------------------------------------------------------------------------------- |
75+
| `and` | `bool` or `null` | `bool` or `null` | `true` if the left and right side are both `true`, `false` otherwise. |
76+
| `or` | `bool` or `null` | `bool` or `null` | `true` if at least one side is `true`, `false` if either side is `false` or `null`. |
77+
78+
### Unary
79+
80+
| Operator | Right Side | Result |
81+
|----------|------------|------------------------------|
82+
| `!` | `bool` | Negates the right-hand side. |
83+
84+
### Comparison
85+
86+
| Operator | Left Side | Right Side | Result |
87+
| -------- | --------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
88+
| `=` | `string`, `number`, `list`, `bool`, or `null` | `string`, `number`, `list`, `bool`, or `null` | `true` if the left and right side are the same type and are strictly equal, `false` otherwise. |
89+
| `!=` | `string`, `number`, `list`, `bool`, or `null` | `string`, `number`, `list`, `bool`, or `null` | `true` if the left and right side are different types or if they are not strictly equal, `false` otherwise. |
90+
| `>` | `number` | `number` | `true` if the left side is greater than the right side. |
91+
| `>=` | `number` | `number` | `true` if the left side is greater than or equal to the right side. |
92+
| `<` | `number` | `number` | `true` if the left side is less than the right side. |
93+
| `<=` | `number` | `number` | `true` if the left side is less than or equal to the right side. |
94+
95+
## Subexpressions
96+
97+
You can use parentheses to group subexpressions for more complex "and / or"
98+
logic as long as the subexpression evaluates to true or false:
99+
100+
| FQL |
101+
| ------------------------------------------------------------------------------------------------------------------------------ |
102+
| `type = 'track' and ( event = 'Click' or match( 'Button *', event ) )` |
103+
| `( type = 'track' or type = 'identify' ) and ( properties.enabled or match( traits.email, '*@company.com' ) )` |
104+
105+
## Functions
106+
107+
| Function | Return Type | Result |
108+
| ----------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
109+
| `contains( s string, sub string )` | `bool` | Returns `true` if string `s` contains string `sub`. |
110+
| `length( list or string )` | `number` | Returns the number of elements in a list or number of bytes (not necessarily characters) in a string. For example, `a` is 1 byte and`ア` is 3 bytes long. |
111+
| `lowercase( s string )` | `string` | Returns `s` with all uppercase characters replaced with their lowercase equivalent. |
112+
| `typeof( value )` | `string` | Returns the type of the given value: `"string"`, `"number"`, `"list"`, `"bool"`, or `"null"`. |
113+
| `match( s string, pattern string )` | `bool` | Returns `true` if the glob pattern `pattern` matches `s`. See below for more details about glob matching. |
114+
115+
Functions handle `null` with sensible defaults to make writing FQL more concise.
116+
For example, you can write `length( userId ) > 0` instead of `typeof( userId ) =
117+
'string' and length( userId ) > 0`.
118+
119+
| Function | Result |
120+
|----------------------------|----------|
121+
| `contains( null, string )` | `false` |
122+
| `length( null )` | `0` |
123+
| `lowercase( null )` | `null` |
124+
| `typeof( null )` | `"null"` |
125+
| `match( null, string )` | `false` |
126+
127+
### `match( string, pattern )`
128+
129+
The `match( string, pattern )` function uses "glob" matching to return `true` if
130+
the given string fully matches a given pattern. Glob patterns are case
131+
sensitive. If you only need to determine if a string contains a given substring,
132+
you should use `contains()`.
133+
134+
| Pattern | Summary |
135+
| ------- | -------------------------------------------------------------------------------------------------------------- |
136+
| `*` | Matches zero or more characters. |
137+
| `?` | Matches one character. |
138+
| `[abc]` | Matches one character in the given list. In this case, `a`, `b`, or `c` will be matched. |
139+
| `[a-z]` | Matches a range of characters. In this case, any lowercase letter will be matched. |
140+
| `\x` | Matches the character `x` literally. This is useful if you need to match `*`, `?` or `]` literally. E.g. `\*`. |
141+
142+
| Pattern | Result | Reason |
143+
| -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
144+
| `match(` `'abcd', 'a*d' )` | `true` | `*` matches zero or more characters. |
145+
| `match( '', '*' )` | `true` | `*` matches zero or more characters. |
146+
| `match( 'abc', 'ab' )` | `false` | The pattern must match the full string. |
147+
| `match( 'abcd', 'a??d' )` | `true` | `?` matches one character only. |
148+
| `match( 'abcd', '*d' )` | `true` | `*` matches one or more characters even at the beginning or end of the string. |
149+
| `match( 'ab*d', 'ab\*d' )` | `true` | `\*` matches the literal character `*`. |
150+
| `match( 'abCd', 'ab[cC]d' )` | `true` | `[cC]` matches either `c` or `C`. |
151+
| `match( 'abcd', 'ab[a-z]d' )` | `true` | `[a-z]` matches any character between `a` and `z`. |
152+
| `match( 'abcd', 'ab[A-Z]d' )` | `false` | `[A-Z]` matches any character between `A` and `Z` but `c` is not in that range because it is lowercase. |
153+
154+
## Errata
155+
156+
### Error Handling
157+
158+
If your FQL statement is invalid (for example `userId = oops"`), your Segment
159+
event will not be sent on to downstream Destinations. We default to not sending
160+
the event to ensure that invalid FQL doesn’t cause sensitive information like
161+
PII to be incorrectly sent to Destinations.
162+
163+
For this reason, we strongly recommend that you use the Destination Filters
164+
"Preview" API to test your filters without impacting your production data.
165+

‎api/config-api/destination-filters/index.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Destination Filters API (Beta)
3+
hidden: true
4+
---
5+
6+
Destination Filter documentation has moved to the [main Config API
7+
site][docs].
8+
9+
[docs]: https://reference.segmentapis.com/#6c12fbe8-9f84-4a6c-848e-76a2325cb3c5

‎api/config-api/images/tracking-plan-block.png

435 KB
Loading

‎api/config-api/images/tracking-plan-connect-source.png

308 KB
Loading

‎api/config-api/images/tracking-plan-debugger.png

373 KB
Loading

‎api/config-api/images/tracking-plan-editor.png

314 KB
Loading

‎api/config-api/images/tracking-plan-schema.png

463 KB
Loading

0 commit comments

Comments
 (0)